2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
8 #define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
19 #include <babeltrace2/types.h>
26 @defgroup api-plugin Plugin loading
29 Plugin loading functions.
31 A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls:
33 @image html plugin.png "A plugin is a package of component classes."
36 The plugin loading API offers functions to <em>find and load</em>
37 existing plugins and use the packaged \bt_p_comp_cls. To \em write a
38 plugin, see \ref api-plugin-dev.
40 There are three types of plugins:
43 <dt>Shared object plugin</dt>
45 <code>.so</code> file on Unix systems;
46 <code>.dll</code> file on Windows systems.
49 <dt>Python 3 plugin</dt>
51 <code>.py</code> file which starts with the
52 <code>bt_plugin_</code> prefix.
55 <dt>Static plugin</dt>
57 A plugin built directly into libbabeltrace2 or into the
62 libbabeltrace2 loads shared object and Python plugins. Those plugins
63 need libbabeltrace2 in turn to create and use \bt_name objects:
65 @image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
67 A plugin is a \ref api-fund-shared-object "shared object": get a new
68 reference with bt_plugin_get_ref() and put an existing reference with
71 Get the number of \bt_comp_cls in a plugin with
72 bt_plugin_get_source_component_class_count(),
73 bt_plugin_get_filter_component_class_count(), and
74 bt_plugin_get_sink_component_class_count().
76 Borrow a \bt_comp_cls by index from a plugin with
77 bt_plugin_borrow_source_component_class_by_index_const(),
78 bt_plugin_borrow_filter_component_class_by_index_const(), and
79 bt_plugin_borrow_sink_component_class_by_index_const().
81 Borrow a \bt_comp_cls by name from a plugin with
82 bt_plugin_borrow_source_component_class_by_name_const(),
83 bt_plugin_borrow_filter_component_class_by_name_const(), and
84 bt_plugin_borrow_sink_component_class_by_name_const().
86 The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
87 bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
88 functions return a <strong>plugin set</strong>, that is, a shared object
89 containing one or more plugins.
91 <h1>Find and load plugins</h1>
93 \anchor api-plugin-def-dirs The bt_plugin_find() and
94 bt_plugin_find_all() functions find and load plugins from the default
95 plugin search directories and from the static plugins.
97 The plugin search order is:
99 -# The colon-separated (or semicolon-separated on Windows) list of
100 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
103 The function searches each directory in this list, without recursing.
105 -# <code>$HOME/.local/lib/babeltrace2/plugins</code>,
108 -# The system \bt_name plugin directory, typically
109 <code>/usr/lib/babeltrace2/plugins</code> or
110 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux,
113 -# The static plugins.
115 Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
116 boolean parameters to include or exclude each of the four locations
119 <h2>Find and load a plugin by name</h2>
121 Find and load a plugin by name with bt_plugin_find().
123 bt_plugin_find() tries to find a plugin with a specific name within
124 the \ref api-plugin-def-dirs "default plugin search directories"
127 <h2>Find and load all the plugins from the default directories</h2>
129 Load all the plugins found in the
130 \ref api-plugin-def-dirs "default plugin search directories"
131 and static plugins with bt_plugin_find_all().
133 <h2>Find and load plugins from a specific file or directory</h2>
135 Find and load plugins from a specific file (<code>.so</code>,
136 <code>.dll</code>, or <code>.py</code>) with
137 bt_plugin_find_all_from_file().
139 A single shared object file can contain multiple plugins, although it's
140 not common practice to do so.
142 Find and load plugins from a specific directory with
143 bt_plugin_find_all_from_dir(). This function can search for plugins
144 within the given directory recursively or not.
146 <h2>Find and load static plugins</h2>
148 Find and load static plugins with bt_plugin_find_all_from_static().
150 A static plugin is built directly into the application or library
151 instead of being a separate shared object file.
153 <h1>Plugin properties</h1>
155 A plugin has the following properties:
159 \anchor api-plugin-prop-name
165 The plugin's name is not related to its file name. For example,
166 a plugin found in the file \c patente.so can be named
169 Use bt_plugin_get_name().
173 \anchor api-plugin-prop-descr
174 \bt_dt_opt Description
177 Description of the plugin.
179 Use bt_plugin_get_description().
183 \anchor api-plugin-prop-author
184 \bt_dt_opt Author name(s)
187 Name(s) of the plugin's author(s).
189 Use bt_plugin_get_author().
193 \anchor api-plugin-prop-license
197 License or license name of the plugin.
199 Use bt_plugin_get_license().
203 \anchor api-plugin-prop-path
207 Path of the file which contains the plugin.
209 A static plugin has no path property.
211 Get bt_plugin_get_path().
215 \anchor api-plugin-prop-version
219 Version of the plugin (major, minor, patch, and extra information).
221 The plugin's version is completely user-defined: the library does
222 not use this property in any way to verify the plugin's
225 Use bt_plugin_get_version().
236 @typedef struct bt_plugin bt_plugin;
241 @typedef struct bt_plugin_set bt_plugin_set;
250 @name Find and load plugins
256 Status codes for bt_plugin_find().
258 typedef enum bt_plugin_find_status
{
263 BT_PLUGIN_FIND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
269 BT_PLUGIN_FIND_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
275 BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
281 BT_PLUGIN_FIND_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
282 } bt_plugin_find_status
;
286 Finds and loads a single plugin which has the name
287 \bt_p{plugin_name} from the default plugin search directories and
288 static plugins, setting \bt_p{*plugin} to the result.
290 This function returns the first plugin which has the name
291 \bt_p{plugin_name} within, in order:
293 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
295 the colon-separated (or semicolon-separated on Windows) list of
296 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
299 The function searches each directory in this list, without recursing.
301 -# <strong>If the \bt_p{find_in_user_dir} parameter is
302 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
305 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
306 system \bt_name plugin directory, typically
307 <code>/usr/lib/babeltrace2/plugins</code> or
308 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
311 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
315 A plugin's name is not related to the name of its file (shared
316 object or Python file). For example, a plugin found in the file
317 \c patente.so can be named <code>Dan</code>.
319 If this function finds a file which looks like a plugin (shared object
320 file or Python file with the \c bt_plugin_ prefix), but it fails to load
321 it for any reason, the function:
324 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
325 <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd>
327 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
328 <dd>Ignores the loading error and continues searching.</dd>
331 If this function doesn't find any plugin, it returns
332 #BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
334 @param[in] plugin_name
335 Name of the plugin to find and load.
336 @param[in] find_in_std_env_var
337 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
338 colon-separated (or semicolon-separated on Windows) list of
339 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
340 @param[in] find_in_user_dir
341 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
342 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
344 @param[in] find_in_sys_dir
345 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
346 the system \bt_name plugin directory.
347 @param[in] find_in_static
348 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
350 @param[in] fail_on_load_error
351 #BT_TRUE to make this function return #BT_PLUGIN_FIND_STATUS_ERROR
352 on any plugin loading error instead of ignoring it.
354 <strong>On success</strong>, \bt_p{*plugin} is a new plugin
355 reference of named \bt_p{plugin_name}.
357 @retval #BT_PLUGIN_FIND_STATUS_OK
359 @retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND
361 @retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
363 @retval #BT_PLUGIN_FIND_STATUS_ERROR
366 @bt_pre_not_null{plugin_name}
368 At least one of the \bt_p{find_in_std_env_var},
369 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
370 \bt_p{find_in_static} parameters is #BT_TRUE.
371 @bt_pre_not_null{plugin}
373 @sa bt_plugin_find_all() —
374 Finds and loads all plugins from the default plugin search
375 directories and static plugins.
377 extern bt_plugin_find_status
bt_plugin_find(const char *plugin_name
,
378 bt_bool find_in_std_env_var
, bt_bool find_in_user_dir
,
379 bt_bool find_in_sys_dir
, bt_bool find_in_static
,
380 bt_bool fail_on_load_error
, const bt_plugin
**plugin
)
385 Status codes for bt_plugin_find_all().
387 typedef enum bt_plugin_find_all_status
{
392 BT_PLUGIN_FIND_ALL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
398 BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
404 BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
410 BT_PLUGIN_FIND_ALL_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
411 } bt_plugin_find_all_status
;
415 Finds and loads all the plugins from the default
416 plugin search directories and static plugins, setting
417 \bt_p{*plugins} to the result.
419 This function returns all the plugins within, in order:
421 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
423 the colon-separated (or semicolon-separated on Windows) list of
424 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
427 The function searches each directory in this list, without recursing.
429 -# <strong>If the \bt_p{find_in_user_dir} parameter is
430 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
433 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
434 system \bt_name plugin directory, typically
435 <code>/usr/lib/babeltrace2/plugins</code> or
436 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
439 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
442 During the search process, if a found plugin shares the name of an
443 already loaded plugin, this function ignores it and continues.
445 If this function finds a file which looks like a plugin (shared object
446 file or Python file with the \c bt_plugin_ prefix), but it fails to load
447 it for any reason, the function:
450 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
451 <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
453 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
454 <dd>Ignores the loading error and continues searching.</dd>
457 If this function doesn't find any plugin, it returns
458 #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
461 @param[in] find_in_std_env_var
462 #BT_TRUE to try to find all the plugins in the
463 colon-separated (or semicolon-separated on Windows) list of
464 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
465 @param[in] find_in_user_dir
466 #BT_TRUE to try to find all the plugins in
467 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
469 @param[in] find_in_sys_dir
470 #BT_TRUE to try to find all the plugins in the system \bt_name
472 @param[in] find_in_static
473 #BT_TRUE to try to find all the plugins in the static plugins.
474 @param[in] fail_on_load_error
475 #BT_TRUE to make this function return
476 #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
479 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
480 reference which contains all the plugins found from the default
481 plugin search directories and static plugins.
483 @retval #BT_PLUGIN_FIND_ALL_STATUS_OK
485 @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
487 @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
489 @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
493 At least one of the \bt_p{find_in_std_env_var},
494 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
495 \bt_p{find_in_static} parameters is #BT_TRUE.
496 @bt_pre_not_null{plugins}
498 @sa bt_plugin_find() —
499 Finds and loads a single plugin by name from the default plugin search
500 directories and static plugins.
502 bt_plugin_find_all_status
bt_plugin_find_all(bt_bool find_in_std_env_var
,
503 bt_bool find_in_user_dir
, bt_bool find_in_sys_dir
,
504 bt_bool find_in_static
, bt_bool fail_on_load_error
,
505 const bt_plugin_set
**plugins
) __BT_NOEXCEPT
;
509 Status codes for bt_plugin_find_all_from_file().
511 typedef enum bt_plugin_find_all_from_file_status
{
516 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
522 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
528 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
534 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
535 } bt_plugin_find_all_from_file_status
;
539 Finds and loads all the plugins from the file with path \bt_p{path},
540 setting \bt_p{*plugins} to the result.
543 A plugin's name is not related to the name of its file (shared
544 object or Python file). For example, a plugin found in the file
545 \c patente.so can be named <code>Dan</code>.
547 If any plugin loading error occurs during this function's execution, the
551 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
552 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
554 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
555 <dd>Ignores the loading error and continues.</dd>
558 If this function doesn't find any plugin, it returns
559 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
563 Path of the file in which to find and load all the plugins.
564 @param[in] fail_on_load_error
565 #BT_TRUE to make this function return
566 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
567 error instead of ignoring it.
569 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
570 reference which contains all the plugins found in the file with path
573 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
575 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
577 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
579 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
582 @bt_pre_not_null{path}
584 \bt_p{path} is the path of a regular file.
585 @bt_pre_not_null{plugins}
587 @sa bt_plugin_find_all_from_dir() —
588 Finds and loads all plugins from a given directory.
590 extern bt_plugin_find_all_from_file_status
bt_plugin_find_all_from_file(
591 const char *path
, bt_bool fail_on_load_error
,
592 const bt_plugin_set
**plugins
) __BT_NOEXCEPT
;
596 Status codes for bt_plugin_find_all_from_dir().
598 typedef enum bt_plugin_find_all_from_dir_status
{
603 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
609 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
615 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
621 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
622 } bt_plugin_find_all_from_dir_status
;
626 Finds and loads all the plugins from the directory with path
627 \bt_p{path}, setting \bt_p{*plugins} to the result.
629 If \bt_p{recurse} is #BT_TRUE, this function recurses into the
630 subdirectories of \bt_p{path} to find plugins.
632 During the search process, if a found plugin shares the name of an
633 already loaded plugin, this function ignores it and continues.
636 As of \bt_name_version_min_maj, the file and directory traversal
639 If any plugin loading error occurs during this function's execution, the
643 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
644 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
646 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
647 <dd>Ignores the loading error and continues.</dd>
650 If this function doesn't find any plugin, it returns
651 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
655 Path of the directory in which to find and load all the plugins.
657 #BT_TRUE to make this function recurse into the subdirectories
659 @param[in] fail_on_load_error
660 #BT_TRUE to make this function return
661 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
662 error instead of ignoring it.
664 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
665 reference which contains all the plugins found in the directory with
668 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
670 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
672 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
674 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
677 @bt_pre_not_null{path}
679 \bt_p{path} is the path of a directory.
680 @bt_pre_not_null{plugins}
682 @sa bt_plugin_find_all_from_file() —
683 Finds and loads all plugins from a given file.
685 extern bt_plugin_find_all_from_dir_status
bt_plugin_find_all_from_dir(
686 const char *path
, bt_bool recurse
, bt_bool fail_on_load_error
,
687 const bt_plugin_set
**plugins
) __BT_NOEXCEPT
;
691 Status codes for bt_plugin_find_all_from_static().
693 typedef enum bt_plugin_find_all_from_static_status
{
698 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
702 No static plugins found.
704 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
710 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
716 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
717 } bt_plugin_find_all_from_static_status
;
721 Finds and loads all the static plugins,
722 setting \bt_p{*plugins} to the result.
724 A static plugin is built directly into the application or library
725 instead of being a separate shared object file.
727 If any plugin loading error occurs during this function's execution, the
731 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
732 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
734 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
735 <dd>Ignores the loading error and continues.</dd>
738 If this function doesn't find any plugin, it returns
739 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
742 @param[in] fail_on_load_error
743 #BT_TRUE to make this function return
744 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
745 error instead of ignoring it.
747 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
748 reference which contains all the static plugins.
750 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
752 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
753 No static plugins found.
754 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
756 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
759 @bt_pre_not_null{path}
760 @bt_pre_not_null{plugins}
762 extern bt_plugin_find_all_from_static_status
bt_plugin_find_all_from_static(
763 bt_bool fail_on_load_error
, const bt_plugin_set
**plugins
)
769 @name Plugin properties
775 Returns the name of the plugin \bt_p{plugin}.
777 See the \ref api-plugin-prop-name "name" property.
780 Plugin of which to get the name.
784 Name of \bt_p{plugin}.
786 The returned pointer remains valid as long as \bt_p{plugin} exists.
789 @bt_pre_not_null{plugin}
791 extern const char *bt_plugin_get_name(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
795 Returns the description of the plugin \bt_p{plugin}.
797 See the \ref api-plugin-prop-descr "description" property.
800 Plugin of which to get description.
804 Description of \bt_p{plugin}, or \c NULL if not available.
806 The returned pointer remains valid as long as \bt_p{plugin} exists.
809 @bt_pre_not_null{plugin}
811 extern const char *bt_plugin_get_description(const bt_plugin
*plugin
)
816 Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
818 See the \ref api-plugin-prop-author "author name(s)" property.
821 Plugin of which to get the author name(s).
825 Author name(s) of \bt_p{plugin}, or \c NULL if not available.
827 The returned pointer remains valid as long as \bt_p{plugin} exists.
830 @bt_pre_not_null{plugin}
832 extern const char *bt_plugin_get_author(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
836 Returns the license text or the license name of the plugin
839 See the \ref api-plugin-prop-license "license" property.
842 Plugin of which to get the license.
846 License of \bt_p{plugin}, or \c NULL if not available.
848 The returned pointer remains valid as long as \bt_p{plugin} exists.
851 @bt_pre_not_null{plugin}
853 extern const char *bt_plugin_get_license(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
857 Returns the path of the file which contains the plugin
860 See the \ref api-plugin-prop-path "path" property.
862 This function returns \c NULL if \bt_p{plugin} is a static plugin
863 because a static plugin has no path property.
866 Plugin of which to get the containing file's path.
870 Path of the file which contains \bt_p{plugin}, or \c NULL if
873 The returned pointer remains valid as long as \bt_p{plugin} exists.
876 @bt_pre_not_null{plugin}
878 extern const char *bt_plugin_get_path(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
882 Returns the version of the plugin \bt_p{plugin}.
884 See the \ref api-plugin-prop-version "version" property.
887 Plugin of which to get the version.
889 <strong>If not \c NULL and this function returns
890 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
891 major version of \bt_p{plugin}.
893 <strong>If not \c NULL and this function returns
894 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
895 minor version of \bt_p{plugin}.
897 <strong>If not \c NULL and this function returns
898 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
899 patch version of \bt_p{plugin}.
902 <strong>If not \c NULL and this function returns
903 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
904 version's extra information of \bt_p{plugin}.
906 \bt_p{*extra} can be \c NULL if the plugin's version has no extra
909 \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
912 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
913 The version of \bt_p{plugin} is available.
914 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
915 The version of \bt_p{plugin} is not available.
917 @bt_pre_not_null{plugin}
919 extern bt_property_availability
bt_plugin_get_version(
920 const bt_plugin
*plugin
, unsigned int *major
,
921 unsigned int *minor
, unsigned int *patch
, const char **extra
)
927 @name Plugin component class access
933 Returns the number of source component classes contained in the
934 plugin \bt_p{plugin}.
937 Plugin of which to get the number of contained source
941 Number of contained source component classes in \bt_p{plugin}.
943 @bt_pre_not_null{plugin}
945 extern uint64_t bt_plugin_get_source_component_class_count(
946 const bt_plugin
*plugin
) __BT_NOEXCEPT
;
950 Returns the number of filter component classes contained in the
951 plugin \bt_p{plugin}.
954 Plugin of which to get the number of contained filter
958 Number of contained filter component classes in \bt_p{plugin}.
960 @bt_pre_not_null{plugin}
962 extern uint64_t bt_plugin_get_filter_component_class_count(
963 const bt_plugin
*plugin
) __BT_NOEXCEPT
;
967 Returns the number of sink component classes contained in the
968 plugin \bt_p{plugin}.
971 Plugin of which to get the number of contained sink
975 Number of contained sink component classes in \bt_p{plugin}.
977 @bt_pre_not_null{plugin}
979 extern uint64_t bt_plugin_get_sink_component_class_count(
980 const bt_plugin
*plugin
) __BT_NOEXCEPT
;
984 Borrows the source component class at index \bt_p{index} from the
985 plugin \bt_p{plugin}.
988 Plugin from which to borrow the source component class at index
991 Index of the source component class to borrow from \bt_p{plugin}.
995 \em Borrowed reference of the source component class of
996 \bt_p{plugin} at index \bt_p{index}.
998 The returned pointer remains valid as long as \bt_p{plugin} exists.
1001 @bt_pre_not_null{plugin}
1003 \bt_p{index} is less than the number of source component classes in
1004 \bt_p{plugin} (as returned by
1005 bt_plugin_get_source_component_class_count()).
1007 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1008 Borrows a source component class by name from a plugin.
1010 extern const bt_component_class_source
*
1011 bt_plugin_borrow_source_component_class_by_index_const(
1012 const bt_plugin
*plugin
, uint64_t index
) __BT_NOEXCEPT
;
1016 Borrows the filter component class at index \bt_p{index} from the
1017 plugin \bt_p{plugin}.
1020 Plugin from which to borrow the filter component class at index
1023 Index of the filter component class to borrow from \bt_p{plugin}.
1027 \em Borrowed reference of the filter component class of
1028 \bt_p{plugin} at index \bt_p{index}.
1030 The returned pointer remains valid as long as \bt_p{plugin} exists.
1033 @bt_pre_not_null{plugin}
1035 \bt_p{index} is less than the number of filter component classes in
1036 \bt_p{plugin} (as returned by
1037 bt_plugin_get_source_component_class_count()).
1039 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1040 Borrows a filter component class by name from a plugin.
1042 extern const bt_component_class_filter
*
1043 bt_plugin_borrow_filter_component_class_by_index_const(
1044 const bt_plugin
*plugin
, uint64_t index
) __BT_NOEXCEPT
;
1048 Borrows the sink component class at index \bt_p{index} from the
1049 plugin \bt_p{plugin}.
1052 Plugin from which to borrow the sink component class at index
1055 Index of the sink component class to borrow from \bt_p{plugin}.
1059 \em Borrowed reference of the sink component class of
1060 \bt_p{plugin} at index \bt_p{index}.
1062 The returned pointer remains valid as long as \bt_p{plugin} exists.
1065 @bt_pre_not_null{plugin}
1067 \bt_p{index} is less than the number of sink component classes in
1068 \bt_p{plugin} (as returned by
1069 bt_plugin_get_source_component_class_count()).
1071 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1072 Borrows a sink component class by name from a plugin.
1074 extern const bt_component_class_sink
*
1075 bt_plugin_borrow_sink_component_class_by_index_const(
1076 const bt_plugin
*plugin
, uint64_t index
) __BT_NOEXCEPT
;
1080 Borrows the source component class named \bt_p{name} from the
1081 plugin \bt_p{plugin}.
1083 If no source component class has the name \bt_p{name} within
1084 \bt_p{plugin}, this function returns \c NULL.
1087 Plugin from which to borrow the source component class named
1090 Name of the source component class to borrow from \bt_p{plugin}.
1094 \em Borrowed reference of the source component class of
1095 \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
1096 class is named \bt_p{name} within \bt_p{plugin}.
1098 The returned pointer remains valid as long as \bt_p{plugin} exists.
1101 @bt_pre_not_null{plugin}
1102 @bt_pre_not_null{name}
1104 @sa bt_plugin_borrow_source_component_class_by_index_const() —
1105 Borrows a source component class by index from a plugin.
1107 extern const bt_component_class_source
*
1108 bt_plugin_borrow_source_component_class_by_name_const(
1109 const bt_plugin
*plugin
, const char *name
) __BT_NOEXCEPT
;
1113 Borrows the filter component class named \bt_p{name} from the
1114 plugin \bt_p{plugin}.
1116 If no filter component class has the name \bt_p{name} within
1117 \bt_p{plugin}, this function returns \c NULL.
1120 Plugin from which to borrow the filter component class named
1123 Name of the filter component class to borrow from \bt_p{plugin}.
1127 \em Borrowed reference of the filter component class of
1128 \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
1129 class is named \bt_p{name} within \bt_p{plugin}.
1131 The returned pointer remains valid as long as \bt_p{plugin} exists.
1134 @bt_pre_not_null{plugin}
1135 @bt_pre_not_null{name}
1137 @sa bt_plugin_borrow_filter_component_class_by_index_const() —
1138 Borrows a filter component class by index from a plugin.
1140 extern const bt_component_class_filter
*
1141 bt_plugin_borrow_filter_component_class_by_name_const(
1142 const bt_plugin
*plugin
, const char *name
) __BT_NOEXCEPT
;
1146 Borrows the sink component class named \bt_p{name} from the
1147 plugin \bt_p{plugin}.
1149 If no sink component class has the name \bt_p{name} within
1150 \bt_p{plugin}, this function returns \c NULL.
1153 Plugin from which to borrow the sink component class named
1156 Name of the sink component class to borrow from \bt_p{plugin}.
1160 \em Borrowed reference of the sink component class of
1161 \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
1162 class is named \bt_p{name} within \bt_p{plugin}.
1164 The returned pointer remains valid as long as \bt_p{plugin} exists.
1167 @bt_pre_not_null{plugin}
1168 @bt_pre_not_null{name}
1170 @sa bt_plugin_borrow_sink_component_class_by_index_const() —
1171 Borrows a sink component class by index from a plugin.
1173 extern const bt_component_class_sink
*
1174 bt_plugin_borrow_sink_component_class_by_name_const(
1175 const bt_plugin
*plugin
, const char *name
) __BT_NOEXCEPT
;
1180 @name Plugin reference count
1186 Increments the \ref api-fund-shared-object "reference count" of
1187 the plugin \bt_p{plugin}.
1191 Plugin of which to increment the reference count.
1196 @sa bt_plugin_put_ref() —
1197 Decrements the reference count of a plugin.
1199 extern void bt_plugin_get_ref(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
1203 Decrements the \ref api-fund-shared-object "reference count" of
1204 the plugin \bt_p{plugin}.
1208 Plugin of which to decrement the reference count.
1213 @sa bt_plugin_get_ref() —
1214 Increments the reference count of a plugin.
1216 extern void bt_plugin_put_ref(const bt_plugin
*plugin
) __BT_NOEXCEPT
;
1220 Decrements the reference count of the plugin \bt_p{_plugin}, and
1221 then sets \bt_p{_plugin} to \c NULL.
1225 Plugin of which to decrement the reference count.
1227 Can contain \c NULL.
1230 @bt_pre_assign_expr{_plugin}
1232 #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \
1234 bt_plugin_put_ref(_plugin); \
1240 Decrements the reference count of the plugin \bt_p{_dst}, sets
1241 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1243 This macro effectively moves a plugin reference from the expression
1244 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1245 \bt_p{_dst} reference.
1249 Destination expression.
1251 Can contain \c NULL.
1257 Can contain \c NULL.
1260 @bt_pre_assign_expr{_dst}
1261 @bt_pre_assign_expr{_src}
1263 #define BT_PLUGIN_MOVE_REF(_dst, _src) \
1265 bt_plugin_put_ref(_dst); \
1273 @name Plugin set plugin access
1279 Returns the number of plugins contained in the
1280 plugin set \bt_p{plugin_set}.
1282 @param[in] plugin_set
1283 Plugin set of which to get the number of contained plugins.
1286 Number of contained plugins in \bt_p{plugin_set}.
1288 @bt_pre_not_null{plugin}
1290 extern uint64_t bt_plugin_set_get_plugin_count(
1291 const bt_plugin_set
*plugin_set
) __BT_NOEXCEPT
;
1295 Borrows the plugin at index \bt_p{index} from the plugin set
1298 @param[in] plugin_set
1299 Plugin set from which to borrow the plugin at index \bt_p{index}.
1301 Index of the plugin to borrow from \bt_p{plugin_set}.
1305 \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1308 The returned pointer remains valid until \bt_p{plugin_set} is
1312 @bt_pre_not_null{plugin_set}
1314 \bt_p{index} is less than the number of plugins in
1315 \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
1317 extern const bt_plugin
*bt_plugin_set_borrow_plugin_by_index_const(
1318 const bt_plugin_set
*plugin_set
, uint64_t index
) __BT_NOEXCEPT
;
1323 @name Plugin set reference count
1329 Increments the \ref api-fund-shared-object "reference count" of
1330 the plugin set \bt_p{plugin_set}.
1332 @param[in] plugin_set
1334 Plugin set of which to increment the reference count.
1339 @sa bt_plugin_set_put_ref() —
1340 Decrements the reference count of a plugin set.
1342 extern void bt_plugin_set_get_ref(const bt_plugin_set
*plugin_set
)
1347 Decrements the \ref api-fund-shared-object "reference count" of
1348 the plugin set \bt_p{plugin_set}.
1350 @param[in] plugin_set
1352 Plugin set of which to decrement the reference count.
1357 @sa bt_plugin_set_get_ref() —
1358 Increments the reference count of a plugin set.
1360 extern void bt_plugin_set_put_ref(const bt_plugin_set
*plugin_set
)
1365 Decrements the reference count of the plugin set \bt_p{_plugin_set},
1366 and then sets \bt_p{_plugin_set} to \c NULL.
1370 Plugin set of which to decrement the reference count.
1372 Can contain \c NULL.
1375 @bt_pre_assign_expr{_plugin_set}
1377 #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \
1379 bt_plugin_set_put_ref(_plugin_set); \
1380 (_plugin_set) = NULL; \
1385 Decrements the reference count of the plugin set \bt_p{_dst}, sets
1386 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1388 This macro effectively moves a plugin set reference from the expression
1389 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1390 \bt_p{_dst} reference.
1394 Destination expression.
1396 Can contain \c NULL.
1402 Can contain \c NULL.
1405 @bt_pre_assign_expr{_dst}
1406 @bt_pre_assign_expr{_src}
1408 #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \
1410 bt_plugin_set_put_ref(_dst); \
1423 #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */