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
);
384 Status codes for bt_plugin_find_all().
386 typedef enum bt_plugin_find_all_status
{
391 BT_PLUGIN_FIND_ALL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
397 BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
403 BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
409 BT_PLUGIN_FIND_ALL_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
410 } bt_plugin_find_all_status
;
414 Finds and loads all the plugins from the default
415 plugin search directories and static plugins, setting
416 \bt_p{*plugins} to the result.
418 This function returns all the plugins within, in order:
420 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
422 the colon-separated (or semicolon-separated on Windows) list of
423 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
426 The function searches each directory in this list, without recursing.
428 -# <strong>If the \bt_p{find_in_user_dir} parameter is
429 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
432 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
433 system \bt_name plugin directory, typically
434 <code>/usr/lib/babeltrace2/plugins</code> or
435 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
438 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
441 During the search process, if a found plugin shares the name of an
442 already loaded plugin, this function ignores it and continues.
444 If this function finds a file which looks like a plugin (shared object
445 file or Python file with the \c bt_plugin_ prefix), but it fails to load
446 it for any reason, the function:
449 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
450 <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
452 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
453 <dd>Ignores the loading error and continues searching.</dd>
456 If this function doesn't find any plugin, it returns
457 #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
460 @param[in] find_in_std_env_var
461 #BT_TRUE to try to find all the plugins in the
462 colon-separated (or semicolon-separated on Windows) list of
463 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
464 @param[in] find_in_user_dir
465 #BT_TRUE to try to find all the plugins in
466 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
468 @param[in] find_in_sys_dir
469 #BT_TRUE to try to find all the plugins in the system \bt_name
471 @param[in] find_in_static
472 #BT_TRUE to try to find all the plugins in the static plugins.
473 @param[in] fail_on_load_error
474 #BT_TRUE to make this function return
475 #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
478 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
479 reference which contains all the plugins found from the default
480 plugin search directories and static plugins.
482 @retval #BT_PLUGIN_FIND_ALL_STATUS_OK
484 @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
486 @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
488 @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
492 At least one of the \bt_p{find_in_std_env_var},
493 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
494 \bt_p{find_in_static} parameters is #BT_TRUE.
495 @bt_pre_not_null{plugins}
497 @sa bt_plugin_find() —
498 Finds and loads a single plugin by name from the default plugin search
499 directories and static plugins.
501 bt_plugin_find_all_status
bt_plugin_find_all(bt_bool find_in_std_env_var
,
502 bt_bool find_in_user_dir
, bt_bool find_in_sys_dir
,
503 bt_bool find_in_static
, bt_bool fail_on_load_error
,
504 const bt_plugin_set
**plugins
);
508 Status codes for bt_plugin_find_all_from_file().
510 typedef enum bt_plugin_find_all_from_file_status
{
515 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
521 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
527 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
533 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
534 } bt_plugin_find_all_from_file_status
;
538 Finds and loads all the plugins from the file with path \bt_p{path},
539 setting \bt_p{*plugins} to the result.
542 A plugin's name is not related to the name of its file (shared
543 object or Python file). For example, a plugin found in the file
544 \c patente.so can be named <code>Dan</code>.
546 If any plugin loading error occurs during this function's execution, the
550 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
551 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
553 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
554 <dd>Ignores the loading error and continues.</dd>
557 If this function doesn't find any plugin, it returns
558 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
562 Path of the file in which to find and load all the plugins.
563 @param[in] fail_on_load_error
564 #BT_TRUE to make this function return
565 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
566 error instead of ignoring it.
568 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
569 reference which contains all the plugins found in the file with path
572 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
574 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
576 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
578 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
581 @bt_pre_not_null{path}
583 \bt_p{path} is the path of a regular file.
584 @bt_pre_not_null{plugins}
586 @sa bt_plugin_find_all_from_dir() —
587 Finds and loads all plugins from a given directory.
589 extern bt_plugin_find_all_from_file_status
bt_plugin_find_all_from_file(
590 const char *path
, bt_bool fail_on_load_error
,
591 const bt_plugin_set
**plugins
);
595 Status codes for bt_plugin_find_all_from_dir().
597 typedef enum bt_plugin_find_all_from_dir_status
{
602 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
608 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
614 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
620 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
621 } bt_plugin_find_all_from_dir_status
;
625 Finds and loads all the plugins from the directory with path
626 \bt_p{path}, setting \bt_p{*plugins} to the result.
628 If \bt_p{recurse} is #BT_TRUE, this function recurses into the
629 subdirectories of \bt_p{path} to find plugins.
631 During the search process, if a found plugin shares the name of an
632 already loaded plugin, this function ignores it and continues.
635 As of \bt_name_version_min_maj, the file and directory traversal
638 If any plugin loading error occurs during this function's execution, the
642 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
643 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
645 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
646 <dd>Ignores the loading error and continues.</dd>
649 If this function doesn't find any plugin, it returns
650 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
654 Path of the directory in which to find and load all the plugins.
656 #BT_TRUE to make this function recurse into the subdirectories
658 @param[in] fail_on_load_error
659 #BT_TRUE to make this function return
660 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
661 error instead of ignoring it.
663 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
664 reference which contains all the plugins found in the directory with
667 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
669 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
671 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
673 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
676 @bt_pre_not_null{path}
678 \bt_p{path} is the path of a directory.
679 @bt_pre_not_null{plugins}
681 @sa bt_plugin_find_all_from_file() —
682 Finds and loads all plugins from a given file.
684 extern bt_plugin_find_all_from_dir_status
bt_plugin_find_all_from_dir(
685 const char *path
, bt_bool recurse
, bt_bool fail_on_load_error
,
686 const bt_plugin_set
**plugins
);
690 Status codes for bt_plugin_find_all_from_static().
692 typedef enum bt_plugin_find_all_from_static_status
{
697 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
701 No static plugins found.
703 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
709 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
715 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
716 } bt_plugin_find_all_from_static_status
;
720 Finds and loads all the static plugins,
721 setting \bt_p{*plugins} to the result.
723 A static plugin is built directly into the application or library
724 instead of being a separate shared object file.
726 If any plugin loading error occurs during this function's execution, the
730 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
731 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
733 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
734 <dd>Ignores the loading error and continues.</dd>
737 If this function doesn't find any plugin, it returns
738 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
741 @param[in] fail_on_load_error
742 #BT_TRUE to make this function return
743 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
744 error instead of ignoring it.
746 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
747 reference which contains all the static plugins.
749 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
751 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
752 No static plugins found.
753 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
755 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
758 @bt_pre_not_null{path}
759 @bt_pre_not_null{plugins}
761 extern bt_plugin_find_all_from_static_status
bt_plugin_find_all_from_static(
762 bt_bool fail_on_load_error
, const bt_plugin_set
**plugins
);
767 @name Plugin properties
773 Returns the name of the plugin \bt_p{plugin}.
775 See the \ref api-plugin-prop-name "name" property.
778 Plugin of which to get the name.
782 Name of \bt_p{plugin}.
784 The returned pointer remains valid as long as \bt_p{plugin} exists.
787 @bt_pre_not_null{plugin}
789 extern const char *bt_plugin_get_name(const bt_plugin
*plugin
);
793 Returns the description of the plugin \bt_p{plugin}.
795 See the \ref api-plugin-prop-descr "description" property.
798 Plugin of which to get description.
802 Description of \bt_p{plugin}, or \c NULL if not available.
804 The returned pointer remains valid as long as \bt_p{plugin} exists.
807 @bt_pre_not_null{plugin}
809 extern const char *bt_plugin_get_description(const bt_plugin
*plugin
);
813 Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
815 See the \ref api-plugin-prop-author "author name(s)" property.
818 Plugin of which to get the author name(s).
822 Author name(s) of \bt_p{plugin}, or \c NULL if not available.
824 The returned pointer remains valid as long as \bt_p{plugin} exists.
827 @bt_pre_not_null{plugin}
829 extern const char *bt_plugin_get_author(const bt_plugin
*plugin
);
833 Returns the license text or the license name of the plugin
836 See the \ref api-plugin-prop-license "license" property.
839 Plugin of which to get the license.
843 License of \bt_p{plugin}, or \c NULL if not available.
845 The returned pointer remains valid as long as \bt_p{plugin} exists.
848 @bt_pre_not_null{plugin}
850 extern const char *bt_plugin_get_license(const bt_plugin
*plugin
);
854 Returns the path of the file which contains the plugin
857 See the \ref api-plugin-prop-path "path" property.
859 This function returns \c NULL if \bt_p{plugin} is a static plugin
860 because a static plugin has no path property.
863 Plugin of which to get the containing file's path.
867 Path of the file which contains \bt_p{plugin}, or \c NULL if
870 The returned pointer remains valid as long as \bt_p{plugin} exists.
873 @bt_pre_not_null{plugin}
875 extern const char *bt_plugin_get_path(const bt_plugin
*plugin
);
879 Returns the version of the plugin \bt_p{plugin}.
881 See the \ref api-plugin-prop-version "version" property.
884 Plugin of which to get the version.
886 <strong>If not \c NULL and this function returns
887 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
888 major version of \bt_p{plugin}.
890 <strong>If not \c NULL and this function returns
891 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
892 minor version of \bt_p{plugin}.
894 <strong>If not \c NULL and this function returns
895 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
896 patch version of \bt_p{plugin}.
899 <strong>If not \c NULL and this function returns
900 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
901 version's extra information of \bt_p{plugin}.
903 \bt_p{*extra} can be \c NULL if the plugin's version has no extra
906 \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
909 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
910 The version of \bt_p{plugin} is available.
911 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
912 The version of \bt_p{plugin} is not available.
914 @bt_pre_not_null{plugin}
916 extern bt_property_availability
bt_plugin_get_version(
917 const bt_plugin
*plugin
, unsigned int *major
,
918 unsigned int *minor
, unsigned int *patch
, const char **extra
);
923 @name Plugin component class access
929 Returns the number of source component classes contained in the
930 plugin \bt_p{plugin}.
933 Plugin of which to get the number of contained source
937 Number of contained source component classes in \bt_p{plugin}.
939 @bt_pre_not_null{plugin}
941 extern uint64_t bt_plugin_get_source_component_class_count(
942 const bt_plugin
*plugin
);
946 Returns the number of filter component classes contained in the
947 plugin \bt_p{plugin}.
950 Plugin of which to get the number of contained filter
954 Number of contained filter component classes in \bt_p{plugin}.
956 @bt_pre_not_null{plugin}
958 extern uint64_t bt_plugin_get_filter_component_class_count(
959 const bt_plugin
*plugin
);
963 Returns the number of sink component classes contained in the
964 plugin \bt_p{plugin}.
967 Plugin of which to get the number of contained sink
971 Number of contained sink component classes in \bt_p{plugin}.
973 @bt_pre_not_null{plugin}
975 extern uint64_t bt_plugin_get_sink_component_class_count(
976 const bt_plugin
*plugin
);
980 Borrows the source component class at index \bt_p{index} from the
981 plugin \bt_p{plugin}.
984 Plugin from which to borrow the source component class at index
987 Index of the source component class to borrow from \bt_p{plugin}.
991 \em Borrowed reference of the source component class of
992 \bt_p{plugin} at index \bt_p{index}.
994 The returned pointer remains valid as long as \bt_p{plugin} exists.
997 @bt_pre_not_null{plugin}
999 \bt_p{index} is less than the number of source component classes in
1000 \bt_p{plugin} (as returned by
1001 bt_plugin_get_source_component_class_count()).
1003 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1004 Borrows a source component class by name from a plugin.
1006 extern const bt_component_class_source
*
1007 bt_plugin_borrow_source_component_class_by_index_const(
1008 const bt_plugin
*plugin
, uint64_t index
);
1012 Borrows the filter component class at index \bt_p{index} from the
1013 plugin \bt_p{plugin}.
1016 Plugin from which to borrow the filter component class at index
1019 Index of the filter component class to borrow from \bt_p{plugin}.
1023 \em Borrowed reference of the filter component class of
1024 \bt_p{plugin} at index \bt_p{index}.
1026 The returned pointer remains valid as long as \bt_p{plugin} exists.
1029 @bt_pre_not_null{plugin}
1031 \bt_p{index} is less than the number of filter component classes in
1032 \bt_p{plugin} (as returned by
1033 bt_plugin_get_source_component_class_count()).
1035 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1036 Borrows a filter component class by name from a plugin.
1038 extern const bt_component_class_filter
*
1039 bt_plugin_borrow_filter_component_class_by_index_const(
1040 const bt_plugin
*plugin
, uint64_t index
);
1044 Borrows the sink component class at index \bt_p{index} from the
1045 plugin \bt_p{plugin}.
1048 Plugin from which to borrow the sink component class at index
1051 Index of the sink component class to borrow from \bt_p{plugin}.
1055 \em Borrowed reference of the sink component class of
1056 \bt_p{plugin} at index \bt_p{index}.
1058 The returned pointer remains valid as long as \bt_p{plugin} exists.
1061 @bt_pre_not_null{plugin}
1063 \bt_p{index} is less than the number of sink component classes in
1064 \bt_p{plugin} (as returned by
1065 bt_plugin_get_source_component_class_count()).
1067 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1068 Borrows a sink component class by name from a plugin.
1070 extern const bt_component_class_sink
*
1071 bt_plugin_borrow_sink_component_class_by_index_const(
1072 const bt_plugin
*plugin
, uint64_t index
);
1076 Borrows the source component class named \bt_p{name} from the
1077 plugin \bt_p{plugin}.
1079 If no source component class has the name \bt_p{name} within
1080 \bt_p{plugin}, this function returns \c NULL.
1083 Plugin from which to borrow the source component class named
1086 Name of the source component class to borrow from \bt_p{plugin}.
1090 \em Borrowed reference of the source component class of
1091 \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
1092 class is named \bt_p{name} within \bt_p{plugin}.
1094 The returned pointer remains valid as long as \bt_p{plugin} exists.
1097 @bt_pre_not_null{plugin}
1098 @bt_pre_not_null{name}
1100 @sa bt_plugin_borrow_source_component_class_by_index_const() —
1101 Borrows a source component class by index from a plugin.
1103 extern const bt_component_class_source
*
1104 bt_plugin_borrow_source_component_class_by_name_const(
1105 const bt_plugin
*plugin
, const char *name
);
1109 Borrows the filter component class named \bt_p{name} from the
1110 plugin \bt_p{plugin}.
1112 If no filter component class has the name \bt_p{name} within
1113 \bt_p{plugin}, this function returns \c NULL.
1116 Plugin from which to borrow the filter component class named
1119 Name of the filter component class to borrow from \bt_p{plugin}.
1123 \em Borrowed reference of the filter component class of
1124 \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
1125 class is named \bt_p{name} within \bt_p{plugin}.
1127 The returned pointer remains valid as long as \bt_p{plugin} exists.
1130 @bt_pre_not_null{plugin}
1131 @bt_pre_not_null{name}
1133 @sa bt_plugin_borrow_filter_component_class_by_index_const() —
1134 Borrows a filter component class by index from a plugin.
1136 extern const bt_component_class_filter
*
1137 bt_plugin_borrow_filter_component_class_by_name_const(
1138 const bt_plugin
*plugin
, const char *name
);
1142 Borrows the sink component class named \bt_p{name} from the
1143 plugin \bt_p{plugin}.
1145 If no sink component class has the name \bt_p{name} within
1146 \bt_p{plugin}, this function returns \c NULL.
1149 Plugin from which to borrow the sink component class named
1152 Name of the sink component class to borrow from \bt_p{plugin}.
1156 \em Borrowed reference of the sink component class of
1157 \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
1158 class is named \bt_p{name} within \bt_p{plugin}.
1160 The returned pointer remains valid as long as \bt_p{plugin} exists.
1163 @bt_pre_not_null{plugin}
1164 @bt_pre_not_null{name}
1166 @sa bt_plugin_borrow_sink_component_class_by_index_const() —
1167 Borrows a sink component class by index from a plugin.
1169 extern const bt_component_class_sink
*
1170 bt_plugin_borrow_sink_component_class_by_name_const(
1171 const bt_plugin
*plugin
, const char *name
);
1176 @name Plugin reference count
1182 Increments the \ref api-fund-shared-object "reference count" of
1183 the plugin \bt_p{plugin}.
1187 Plugin of which to increment the reference count.
1192 @sa bt_plugin_put_ref() —
1193 Decrements the reference count of a plugin.
1195 extern void bt_plugin_get_ref(const bt_plugin
*plugin
);
1199 Decrements the \ref api-fund-shared-object "reference count" of
1200 the plugin \bt_p{plugin}.
1204 Plugin of which to decrement the reference count.
1209 @sa bt_plugin_get_ref() —
1210 Increments the reference count of a plugin.
1212 extern void bt_plugin_put_ref(const bt_plugin
*plugin
);
1216 Decrements the reference count of the plugin \bt_p{_plugin}, and
1217 then sets \bt_p{_plugin} to \c NULL.
1221 Plugin of which to decrement the reference count.
1223 Can contain \c NULL.
1226 @bt_pre_assign_expr{_plugin}
1228 #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \
1230 bt_plugin_put_ref(_plugin); \
1236 Decrements the reference count of the plugin \bt_p{_dst}, sets
1237 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1239 This macro effectively moves a plugin reference from the expression
1240 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1241 \bt_p{_dst} reference.
1245 Destination expression.
1247 Can contain \c NULL.
1253 Can contain \c NULL.
1256 @bt_pre_assign_expr{_dst}
1257 @bt_pre_assign_expr{_src}
1259 #define BT_PLUGIN_MOVE_REF(_dst, _src) \
1261 bt_plugin_put_ref(_dst); \
1269 @name Plugin set plugin access
1275 Returns the number of plugins contained in the
1276 plugin set \bt_p{plugin_set}.
1278 @param[in] plugin_set
1279 Plugin set of which to get the number of contained plugins.
1282 Number of contained plugins in \bt_p{plugin_set}.
1284 @bt_pre_not_null{plugin}
1286 extern uint64_t bt_plugin_set_get_plugin_count(
1287 const bt_plugin_set
*plugin_set
);
1291 Borrows the plugin at index \bt_p{index} from the plugin set
1294 @param[in] plugin_set
1295 Plugin set from which to borrow the plugin at index \bt_p{index}.
1297 Index of the plugin to borrow from \bt_p{plugin_set}.
1301 \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1304 The returned pointer remains valid until \bt_p{plugin_set} is
1308 @bt_pre_not_null{plugin_set}
1310 \bt_p{index} is less than the number of plugins in
1311 \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
1313 extern const bt_plugin
*bt_plugin_set_borrow_plugin_by_index_const(
1314 const bt_plugin_set
*plugin_set
, uint64_t index
);
1319 @name Plugin set reference count
1325 Increments the \ref api-fund-shared-object "reference count" of
1326 the plugin set \bt_p{plugin_set}.
1328 @param[in] plugin_set
1330 Plugin set of which to increment the reference count.
1335 @sa bt_plugin_set_put_ref() —
1336 Decrements the reference count of a plugin set.
1338 extern void bt_plugin_set_get_ref(const bt_plugin_set
*plugin_set
);
1342 Decrements the \ref api-fund-shared-object "reference count" of
1343 the plugin set \bt_p{plugin_set}.
1345 @param[in] plugin_set
1347 Plugin set of which to decrement the reference count.
1352 @sa bt_plugin_set_get_ref() —
1353 Increments the reference count of a plugin set.
1355 extern void bt_plugin_set_put_ref(const bt_plugin_set
*plugin_set
);
1359 Decrements the reference count of the plugin set \bt_p{_plugin_set},
1360 and then sets \bt_p{_plugin_set} to \c NULL.
1364 Plugin set of which to decrement the reference count.
1366 Can contain \c NULL.
1369 @bt_pre_assign_expr{_plugin_set}
1371 #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \
1373 bt_plugin_set_put_ref(_plugin_set); \
1374 (_plugin_set) = NULL; \
1379 Decrements the reference count of the plugin set \bt_p{_dst}, sets
1380 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1382 This macro effectively moves a plugin set reference from the expression
1383 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1384 \bt_p{_dst} reference.
1388 Destination expression.
1390 Can contain \c NULL.
1396 Can contain \c NULL.
1399 @bt_pre_assign_expr{_dst}
1400 @bt_pre_assign_expr{_src}
1402 #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \
1404 bt_plugin_set_put_ref(_dst); \
1417 #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */