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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
17 #include <babeltrace2/types.h>
24 @defgroup api-plugin Plugin loading
27 Plugin loading functions.
29 A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls:
31 @image html plugin.png "A plugin is a package of component classes."
34 The plugin loading API offers functions to <em>find and load</em>
35 existing plugins and use the packaged \bt_p_comp_cls. To \em write a
36 plugin, see \ref api-plugin-dev.
38 There are three types of plugins:
41 <dt>Shared object plugin</dt>
43 <code>.so</code> file on Unix systems;
44 <code>.dll</code> file on Windows systems.
47 <dt>Python 3 plugin</dt>
49 <code>.py</code> file which starts with the
50 <code>bt_plugin_</code> prefix.
53 <dt>Static plugin</dt>
55 A plugin built directly into libbabeltrace2 or into the
60 libbabeltrace2 loads shared object and Python plugins. Those plugins
61 need libbabeltrace2 in turn to create and use \bt_name objects:
63 @image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
65 A plugin is a \ref api-fund-shared-object "shared object": get a new
66 reference with bt_plugin_get_ref() and put an existing reference with
69 Get the number of \bt_comp_cls in a plugin with
70 bt_plugin_get_source_component_class_count(),
71 bt_plugin_get_filter_component_class_count(), and
72 bt_plugin_get_sink_component_class_count().
74 Borrow a \bt_comp_cls by index from a plugin with
75 bt_plugin_borrow_source_component_class_by_index_const(),
76 bt_plugin_borrow_filter_component_class_by_index_const(), and
77 bt_plugin_borrow_sink_component_class_by_index_const().
79 Borrow a \bt_comp_cls by name from a plugin with
80 bt_plugin_borrow_source_component_class_by_name_const(),
81 bt_plugin_borrow_filter_component_class_by_name_const(), and
82 bt_plugin_borrow_sink_component_class_by_name_const().
84 The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
85 bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
86 functions return a <strong>plugin set</strong>, that is, a shared object
87 containing one or more plugins.
89 <h1>Find and load plugins</h1>
91 \anchor api-plugin-def-dirs The bt_plugin_find() and
92 bt_plugin_find_all() functions find and load plugins from the default
93 plugin search directories and from the static plugins.
95 The plugin search order is:
97 -# The colon-separated (or semicolon-separated on Windows) list of
98 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
101 The function searches each directory in this list, without recursing.
103 -# <code>$HOME/.local/lib/babeltrace2/plugins</code>,
106 -# The system \bt_name plugin directory, typically
107 <code>/usr/lib/babeltrace2/plugins</code> or
108 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux,
111 -# The static plugins.
113 Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
114 boolean parameters to include or exclude each of the four locations
117 <h2>Find and load a plugin by name</h2>
119 Find and load a plugin by name with bt_plugin_find().
121 bt_plugin_find() tries to find a plugin with a specific name within
122 the \ref api-plugin-def-dirs "default plugin search directories"
125 <h2>Find and load all the plugins from the default directories</h2>
127 Load all the plugins found in the
128 \ref api-plugin-def-dirs "default plugin search directories"
129 and static plugins with bt_plugin_find_all().
131 <h2>Find and load plugins from a specific file or directory</h2>
133 Find and load plugins from a specific file (<code>.so</code>,
134 <code>.dll</code>, or <code>.py</code>) with
135 bt_plugin_find_all_from_file().
137 A single shared object file can contain multiple plugins, although it's
138 not common practice to do so.
140 Find and load plugins from a specific directory with
141 bt_plugin_find_all_from_dir(). This function can search for plugins
142 within the given directory recursively or not.
144 <h2>Find and load static plugins</h2>
146 Find and load static plugins with bt_plugin_find_all_from_static().
148 A static plugin is built directly into the application or library
149 instead of being a separate shared object file.
151 <h1>Plugin properties</h1>
153 A plugin has the following properties:
157 \anchor api-plugin-prop-name
163 The plugin's name is not related to its file name. For example,
164 a plugin found in the file \c patente.so can be named
167 Use bt_plugin_get_name().
171 \anchor api-plugin-prop-descr
172 \bt_dt_opt Description
175 Description of the plugin.
177 Use bt_plugin_get_description().
181 \anchor api-plugin-prop-author
182 \bt_dt_opt Author name(s)
185 Name(s) of the plugin's author(s).
187 Use bt_plugin_get_author().
191 \anchor api-plugin-prop-license
195 License or license name of the plugin.
197 Use bt_plugin_get_license().
201 \anchor api-plugin-prop-path
205 Path of the file which contains the plugin.
207 A static plugin has no path property.
209 Get bt_plugin_get_path().
213 \anchor api-plugin-prop-version
217 Version of the plugin (major, minor, patch, and extra information).
219 The plugin's version is completely user-defined: the library does
220 not use this property in any way to verify the plugin's
223 Use bt_plugin_get_version().
234 @typedef struct bt_plugin bt_plugin;
239 @typedef struct bt_plugin_set bt_plugin_set;
248 @name Find and load plugins
254 Status codes for bt_plugin_find().
256 typedef enum bt_plugin_find_status
{
261 BT_PLUGIN_FIND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
267 BT_PLUGIN_FIND_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
273 BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
279 BT_PLUGIN_FIND_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
280 } bt_plugin_find_status
;
284 Finds and loads a single plugin which has the name
285 \bt_p{plugin_name} from the default plugin search directories and
286 static plugins, setting \bt_p{*plugin} to the result.
288 This function returns the first plugin which has the name
289 \bt_p{plugin_name} within, in order:
291 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
293 the colon-separated (or semicolon-separated on Windows) list of
294 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
297 The function searches each directory in this list, without recursing.
299 -# <strong>If the \bt_p{find_in_user_dir} parameter is
300 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
303 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
304 system \bt_name plugin directory, typically
305 <code>/usr/lib/babeltrace2/plugins</code> or
306 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
309 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
313 A plugin's name is not related to the name of its file (shared
314 object or Python file). For example, a plugin found in the file
315 \c patente.so can be named <code>Dan</code>.
317 If this function finds a file which looks like a plugin (shared object
318 file or Python file with the \c bt_plugin_ prefix), but it fails to load
319 it for any reason, the function:
322 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
323 <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd>
325 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
326 <dd>Ignores the loading error and continues searching.</dd>
329 If this function doesn't find any plugin, it returns
330 #BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
332 @param[in] plugin_name
333 Name of the plugin to find and load.
334 @param[in] find_in_std_env_var
335 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
336 colon-separated (or semicolon-separated on Windows) list of
337 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
338 @param[in] find_in_user_dir
339 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
340 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
342 @param[in] find_in_sys_dir
343 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
344 the system \bt_name plugin directory.
345 @param[in] find_in_static
346 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
348 @param[in] fail_on_load_error
349 #BT_TRUE to make this function return #BT_PLUGIN_FIND_STATUS_ERROR
350 on any plugin loading error instead of ignoring it.
352 <strong>On success</strong>, \bt_p{*plugin} is a new plugin
353 reference of named \bt_p{plugin_name}.
355 @retval #BT_PLUGIN_FIND_STATUS_OK
357 @retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND
359 @retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
361 @retval #BT_PLUGIN_FIND_STATUS_ERROR
364 @bt_pre_not_null{plugin_name}
366 At least one of the \bt_p{find_in_std_env_var},
367 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
368 \bt_p{find_in_static} parameters is #BT_TRUE.
369 @bt_pre_not_null{plugin}
371 @sa bt_plugin_find_all() —
372 Finds and loads all plugins from the default plugin search
373 directories and static plugins.
375 extern bt_plugin_find_status
bt_plugin_find(const char *plugin_name
,
376 bt_bool find_in_std_env_var
, bt_bool find_in_user_dir
,
377 bt_bool find_in_sys_dir
, bt_bool find_in_static
,
378 bt_bool fail_on_load_error
, const bt_plugin
**plugin
);
382 Status codes for bt_plugin_find_all().
384 typedef enum bt_plugin_find_all_status
{
389 BT_PLUGIN_FIND_ALL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
395 BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
401 BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
407 BT_PLUGIN_FIND_ALL_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
408 } bt_plugin_find_all_status
;
412 Finds and loads all the plugins from the default
413 plugin search directories and static plugins, setting
414 \bt_p{*plugins} to the result.
416 This function returns all the plugins within, in order:
418 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
420 the colon-separated (or semicolon-separated on Windows) list of
421 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
424 The function searches each directory in this list, without recursing.
426 -# <strong>If the \bt_p{find_in_user_dir} parameter is
427 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
430 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
431 system \bt_name plugin directory, typically
432 <code>/usr/lib/babeltrace2/plugins</code> or
433 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
436 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
439 During the search process, if a found plugin shares the name of an
440 already loaded plugin, this function ignores it and continues.
442 If this function finds a file which looks like a plugin (shared object
443 file or Python file with the \c bt_plugin_ prefix), but it fails to load
444 it for any reason, the function:
447 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
448 <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
450 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
451 <dd>Ignores the loading error and continues searching.</dd>
454 If this function doesn't find any plugin, it returns
455 #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
458 @param[in] find_in_std_env_var
459 #BT_TRUE to try to find all the plugins in the
460 colon-separated (or semicolon-separated on Windows) list of
461 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
462 @param[in] find_in_user_dir
463 #BT_TRUE to try to find all the plugins in
464 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
466 @param[in] find_in_sys_dir
467 #BT_TRUE to try to find all the plugins in the system \bt_name
469 @param[in] find_in_static
470 #BT_TRUE to try to find all the plugins in the static plugins.
471 @param[in] fail_on_load_error
472 #BT_TRUE to make this function return
473 #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
476 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
477 reference which contains all the plugins found from the default
478 plugin search directories and static plugins.
480 @retval #BT_PLUGIN_FIND_ALL_STATUS_OK
482 @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
484 @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
486 @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
490 At least one of the \bt_p{find_in_std_env_var},
491 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
492 \bt_p{find_in_static} parameters is #BT_TRUE.
493 @bt_pre_not_null{plugins}
495 @sa bt_plugin_find() —
496 Finds and loads a single plugin by name from the default plugin search
497 directories and static plugins.
499 bt_plugin_find_all_status
bt_plugin_find_all(bt_bool find_in_std_env_var
,
500 bt_bool find_in_user_dir
, bt_bool find_in_sys_dir
,
501 bt_bool find_in_static
, bt_bool fail_on_load_error
,
502 const bt_plugin_set
**plugins
);
506 Status codes for bt_plugin_find_all_from_file().
508 typedef enum bt_plugin_find_all_from_file_status
{
513 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
519 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
525 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
531 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
532 } bt_plugin_find_all_from_file_status
;
536 Finds and loads all the plugins from the file with path \bt_p{path},
537 setting \bt_p{*plugins} to the result.
540 A plugin's name is not related to the name of its file (shared
541 object or Python file). For example, a plugin found in the file
542 \c patente.so can be named <code>Dan</code>.
544 If any plugin loading error occurs during this function's execution, the
548 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
549 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
551 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
552 <dd>Ignores the loading error and continues.</dd>
555 If this function doesn't find any plugin, it returns
556 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
560 Path of the file in which to find and load all the plugins.
561 @param[in] fail_on_load_error
562 #BT_TRUE to make this function return
563 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
564 error instead of ignoring it.
566 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
567 reference which contains all the plugins found in the file with path
570 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
572 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
574 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
576 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
579 @bt_pre_not_null{path}
581 \bt_p{path} is the path of a regular file.
582 @bt_pre_not_null{plugins}
584 @sa bt_plugin_find_all_from_dir() —
585 Finds and loads all plugins from a given directory.
587 extern bt_plugin_find_all_from_file_status
bt_plugin_find_all_from_file(
588 const char *path
, bt_bool fail_on_load_error
,
589 const bt_plugin_set
**plugins
);
593 Status codes for bt_plugin_find_all_from_dir().
595 typedef enum bt_plugin_find_all_from_dir_status
{
600 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
606 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
612 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
618 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
619 } bt_plugin_find_all_from_dir_status
;
623 Finds and loads all the plugins from the directory with path
624 \bt_p{path}, setting \bt_p{*plugins} to the result.
626 If \bt_p{recurse} is #BT_TRUE, this function recurses into the
627 subdirectories of \bt_p{path} to find plugins.
629 During the search process, if a found plugin shares the name of an
630 already loaded plugin, this function ignores it and continues.
633 As of \bt_name_version_min_maj, the file and directory traversal
636 If any plugin loading error occurs during this function's execution, the
640 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
641 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
643 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
644 <dd>Ignores the loading error and continues.</dd>
647 If this function doesn't find any plugin, it returns
648 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
652 Path of the directory in which to find and load all the plugins.
654 #BT_TRUE to make this function recurse into the subdirectories
656 @param[in] fail_on_load_error
657 #BT_TRUE to make this function return
658 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
659 error instead of ignoring it.
661 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
662 reference which contains all the plugins found in the directory with
665 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
667 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
669 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
671 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
674 @bt_pre_not_null{path}
676 \bt_p{path} is the path of a directory.
677 @bt_pre_not_null{plugins}
679 @sa bt_plugin_find_all_from_file() —
680 Finds and loads all plugins from a given file.
682 extern bt_plugin_find_all_from_dir_status
bt_plugin_find_all_from_dir(
683 const char *path
, bt_bool recurse
, bt_bool fail_on_load_error
,
684 const bt_plugin_set
**plugins
);
688 Status codes for bt_plugin_find_all_from_static().
690 typedef enum bt_plugin_find_all_from_static_status
{
695 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
699 No static plugins found.
701 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
707 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
713 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
714 } bt_plugin_find_all_from_static_status
;
718 Finds and loads all the static plugins,
719 setting \bt_p{*plugins} to the result.
721 A static plugin is built directly into the application or library
722 instead of being a separate shared object file.
724 If any plugin loading error occurs during this function's execution, the
728 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
729 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
731 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
732 <dd>Ignores the loading error and continues.</dd>
735 If this function doesn't find any plugin, it returns
736 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
739 @param[in] fail_on_load_error
740 #BT_TRUE to make this function return
741 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
742 error instead of ignoring it.
744 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
745 reference which contains all the static plugins.
747 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
749 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
750 No static plugins found.
751 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
753 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
756 @bt_pre_not_null{path}
757 @bt_pre_not_null{plugins}
759 extern bt_plugin_find_all_from_static_status
bt_plugin_find_all_from_static(
760 bt_bool fail_on_load_error
, const bt_plugin_set
**plugins
);
765 @name Plugin properties
771 Returns the name of the plugin \bt_p{plugin}.
773 See the \ref api-plugin-prop-name "name" property.
776 Plugin of which to get the name.
780 Name of \bt_p{plugin}.
782 The returned pointer remains valid as long as \bt_p{plugin} exists.
785 @bt_pre_not_null{plugin}
787 extern const char *bt_plugin_get_name(const bt_plugin
*plugin
);
791 Returns the description of the plugin \bt_p{plugin}.
793 See the \ref api-plugin-prop-descr "description" property.
796 Plugin of which to get description.
800 Description of \bt_p{plugin}, or \c NULL if not available.
802 The returned pointer remains valid as long as \bt_p{plugin} exists.
805 @bt_pre_not_null{plugin}
807 extern const char *bt_plugin_get_description(const bt_plugin
*plugin
);
811 Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
813 See the \ref api-plugin-prop-author "author name(s)" property.
816 Plugin of which to get the author name(s).
820 Author name(s) of \bt_p{plugin}, or \c NULL if not available.
822 The returned pointer remains valid as long as \bt_p{plugin} exists.
825 @bt_pre_not_null{plugin}
827 extern const char *bt_plugin_get_author(const bt_plugin
*plugin
);
831 Returns the license text or the license name of the plugin
834 See the \ref api-plugin-prop-license "license" property.
837 Plugin of which to get the license.
841 License of \bt_p{plugin}, or \c NULL if not available.
843 The returned pointer remains valid as long as \bt_p{plugin} exists.
846 @bt_pre_not_null{plugin}
848 extern const char *bt_plugin_get_license(const bt_plugin
*plugin
);
852 Returns the path of the file which contains the plugin
855 See the \ref api-plugin-prop-path "path" property.
857 This function returns \c NULL if \bt_p{plugin} is a static plugin
858 because a static plugin has no path property.
861 Plugin of which to get the containing file's path.
865 Path of the file which contains \bt_p{plugin}, or \c NULL if
868 The returned pointer remains valid as long as \bt_p{plugin} exists.
871 @bt_pre_not_null{plugin}
873 extern const char *bt_plugin_get_path(const bt_plugin
*plugin
);
877 Returns the version of the plugin \bt_p{plugin}.
879 See the \ref api-plugin-prop-version "version" property.
882 Plugin of which to get the version.
884 <strong>If not \c NULL and this function returns
885 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
886 major version of \bt_p{plugin}.
888 <strong>If not \c NULL and this function returns
889 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
890 minor version of \bt_p{plugin}.
892 <strong>If not \c NULL and this function returns
893 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
894 patch version of \bt_p{plugin}.
897 <strong>If not \c NULL and this function returns
898 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
899 version's extra information of \bt_p{plugin}.
901 \bt_p{*extra} can be \c NULL if the plugin's version has no extra
904 \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
907 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
908 The version of \bt_p{plugin} is available.
909 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
910 The version of \bt_p{plugin} is not available.
912 @bt_pre_not_null{plugin}
914 extern bt_property_availability
bt_plugin_get_version(
915 const bt_plugin
*plugin
, unsigned int *major
,
916 unsigned int *minor
, unsigned int *patch
, const char **extra
);
921 @name Plugin component class access
927 Returns the number of source component classes contained in the
928 plugin \bt_p{plugin}.
931 Plugin of which to get the number of contained source
935 Number of contained source component classes in \bt_p{plugin}.
937 @bt_pre_not_null{plugin}
939 extern uint64_t bt_plugin_get_source_component_class_count(
940 const bt_plugin
*plugin
);
944 Returns the number of filter component classes contained in the
945 plugin \bt_p{plugin}.
948 Plugin of which to get the number of contained filter
952 Number of contained filter component classes in \bt_p{plugin}.
954 @bt_pre_not_null{plugin}
956 extern uint64_t bt_plugin_get_filter_component_class_count(
957 const bt_plugin
*plugin
);
961 Returns the number of sink component classes contained in the
962 plugin \bt_p{plugin}.
965 Plugin of which to get the number of contained sink
969 Number of contained sink component classes in \bt_p{plugin}.
971 @bt_pre_not_null{plugin}
973 extern uint64_t bt_plugin_get_sink_component_class_count(
974 const bt_plugin
*plugin
);
978 Borrows the source component class at index \bt_p{index} from the
979 plugin \bt_p{plugin}.
982 Plugin from which to borrow the source component class at index
985 Index of the source component class to borrow from \bt_p{plugin}.
989 \em Borrowed reference of the source component class of
990 \bt_p{plugin} at index \bt_p{index}.
992 The returned pointer remains valid as long as \bt_p{plugin} exists.
995 @bt_pre_not_null{plugin}
997 \bt_p{index} is less than the number of source component classes in
998 \bt_p{plugin} (as returned by
999 bt_plugin_get_source_component_class_count()).
1001 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1002 Borrows a source component class by name from a plugin.
1004 extern const bt_component_class_source
*
1005 bt_plugin_borrow_source_component_class_by_index_const(
1006 const bt_plugin
*plugin
, uint64_t index
);
1010 Borrows the filter component class at index \bt_p{index} from the
1011 plugin \bt_p{plugin}.
1014 Plugin from which to borrow the filter component class at index
1017 Index of the filter component class to borrow from \bt_p{plugin}.
1021 \em Borrowed reference of the filter component class of
1022 \bt_p{plugin} at index \bt_p{index}.
1024 The returned pointer remains valid as long as \bt_p{plugin} exists.
1027 @bt_pre_not_null{plugin}
1029 \bt_p{index} is less than the number of filter component classes in
1030 \bt_p{plugin} (as returned by
1031 bt_plugin_get_source_component_class_count()).
1033 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1034 Borrows a filter component class by name from a plugin.
1036 extern const bt_component_class_filter
*
1037 bt_plugin_borrow_filter_component_class_by_index_const(
1038 const bt_plugin
*plugin
, uint64_t index
);
1042 Borrows the sink component class at index \bt_p{index} from the
1043 plugin \bt_p{plugin}.
1046 Plugin from which to borrow the sink component class at index
1049 Index of the sink component class to borrow from \bt_p{plugin}.
1053 \em Borrowed reference of the sink component class of
1054 \bt_p{plugin} at index \bt_p{index}.
1056 The returned pointer remains valid as long as \bt_p{plugin} exists.
1059 @bt_pre_not_null{plugin}
1061 \bt_p{index} is less than the number of sink component classes in
1062 \bt_p{plugin} (as returned by
1063 bt_plugin_get_source_component_class_count()).
1065 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1066 Borrows a sink component class by name from a plugin.
1068 extern const bt_component_class_sink
*
1069 bt_plugin_borrow_sink_component_class_by_index_const(
1070 const bt_plugin
*plugin
, uint64_t index
);
1074 Borrows the source component class named \bt_p{name} from the
1075 plugin \bt_p{plugin}.
1077 If no source component class has the name \bt_p{name} within
1078 \bt_p{plugin}, this function returns \c NULL.
1081 Plugin from which to borrow the source component class named
1084 Name of the source component class to borrow from \bt_p{plugin}.
1088 \em Borrowed reference of the source component class of
1089 \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
1090 class is named \bt_p{name} within \bt_p{plugin}.
1092 The returned pointer remains valid as long as \bt_p{plugin} exists.
1095 @bt_pre_not_null{plugin}
1096 @bt_pre_not_null{name}
1098 @sa bt_plugin_borrow_source_component_class_by_index_const() —
1099 Borrows a source component class by index from a plugin.
1101 extern const bt_component_class_source
*
1102 bt_plugin_borrow_source_component_class_by_name_const(
1103 const bt_plugin
*plugin
, const char *name
);
1107 Borrows the filter component class named \bt_p{name} from the
1108 plugin \bt_p{plugin}.
1110 If no filter component class has the name \bt_p{name} within
1111 \bt_p{plugin}, this function returns \c NULL.
1114 Plugin from which to borrow the filter component class named
1117 Name of the filter component class to borrow from \bt_p{plugin}.
1121 \em Borrowed reference of the filter component class of
1122 \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
1123 class is named \bt_p{name} within \bt_p{plugin}.
1125 The returned pointer remains valid as long as \bt_p{plugin} exists.
1128 @bt_pre_not_null{plugin}
1129 @bt_pre_not_null{name}
1131 @sa bt_plugin_borrow_filter_component_class_by_index_const() —
1132 Borrows a filter component class by index from a plugin.
1134 extern const bt_component_class_filter
*
1135 bt_plugin_borrow_filter_component_class_by_name_const(
1136 const bt_plugin
*plugin
, const char *name
);
1140 Borrows the sink component class named \bt_p{name} from the
1141 plugin \bt_p{plugin}.
1143 If no sink component class has the name \bt_p{name} within
1144 \bt_p{plugin}, this function returns \c NULL.
1147 Plugin from which to borrow the sink component class named
1150 Name of the sink component class to borrow from \bt_p{plugin}.
1154 \em Borrowed reference of the sink component class of
1155 \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
1156 class is named \bt_p{name} within \bt_p{plugin}.
1158 The returned pointer remains valid as long as \bt_p{plugin} exists.
1161 @bt_pre_not_null{plugin}
1162 @bt_pre_not_null{name}
1164 @sa bt_plugin_borrow_sink_component_class_by_index_const() —
1165 Borrows a sink component class by index from a plugin.
1167 extern const bt_component_class_sink
*
1168 bt_plugin_borrow_sink_component_class_by_name_const(
1169 const bt_plugin
*plugin
, const char *name
);
1174 @name Plugin reference count
1180 Increments the \ref api-fund-shared-object "reference count" of
1181 the plugin \bt_p{plugin}.
1185 Plugin of which to increment the reference count.
1190 @sa bt_plugin_put_ref() —
1191 Decrements the reference count of a plugin.
1193 extern void bt_plugin_get_ref(const bt_plugin
*plugin
);
1197 Decrements the \ref api-fund-shared-object "reference count" of
1198 the plugin \bt_p{plugin}.
1202 Plugin of which to decrement the reference count.
1207 @sa bt_plugin_get_ref() —
1208 Increments the reference count of a plugin.
1210 extern void bt_plugin_put_ref(const bt_plugin
*plugin
);
1214 Decrements the reference count of the plugin \bt_p{_plugin}, and
1215 then sets \bt_p{_plugin} to \c NULL.
1219 Plugin of which to decrement the reference count.
1221 Can contain \c NULL.
1224 @bt_pre_assign_expr{_plugin}
1226 #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \
1228 bt_plugin_put_ref(_plugin); \
1234 Decrements the reference count of the plugin \bt_p{_dst}, sets
1235 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1237 This macro effectively moves a plugin reference from the expression
1238 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1239 \bt_p{_dst} reference.
1243 Destination expression.
1245 Can contain \c NULL.
1251 Can contain \c NULL.
1254 @bt_pre_assign_expr{_dst}
1255 @bt_pre_assign_expr{_src}
1257 #define BT_PLUGIN_MOVE_REF(_dst, _src) \
1259 bt_plugin_put_ref(_dst); \
1267 @name Plugin set plugin access
1273 Returns the number of plugins contained in the
1274 plugin set \bt_p{plugin_set}.
1276 @param[in] plugin_set
1277 Plugin set of which to get the number of contained plugins.
1280 Number of contained plugins in \bt_p{plugin_set}.
1282 @bt_pre_not_null{plugin}
1284 extern uint64_t bt_plugin_set_get_plugin_count(
1285 const bt_plugin_set
*plugin_set
);
1289 Borrows the plugin at index \bt_p{index} from the plugin set
1292 @param[in] plugin_set
1293 Plugin set from which to borrow the plugin at index \bt_p{index}.
1295 Index of the plugin to borrow from \bt_p{plugin_set}.
1299 \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1302 The returned pointer remains valid until \bt_p{plugin_set} is
1306 @bt_pre_not_null{plugin_set}
1308 \bt_p{index} is less than the number of plugins in
1309 \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
1311 extern const bt_plugin
*bt_plugin_set_borrow_plugin_by_index_const(
1312 const bt_plugin_set
*plugin_set
, uint64_t index
);
1317 @name Plugin set reference count
1323 Increments the \ref api-fund-shared-object "reference count" of
1324 the plugin set \bt_p{plugin_set}.
1326 @param[in] plugin_set
1328 Plugin set of which to increment the reference count.
1333 @sa bt_plugin_set_put_ref() —
1334 Decrements the reference count of a plugin set.
1336 extern void bt_plugin_set_get_ref(const bt_plugin_set
*plugin_set
);
1340 Decrements the \ref api-fund-shared-object "reference count" of
1341 the plugin set \bt_p{plugin_set}.
1343 @param[in] plugin_set
1345 Plugin set of which to decrement the reference count.
1350 @sa bt_plugin_set_get_ref() —
1351 Increments the reference count of a plugin set.
1353 extern void bt_plugin_set_put_ref(const bt_plugin_set
*plugin_set
);
1357 Decrements the reference count of the plugin set \bt_p{_plugin_set},
1358 and then sets \bt_p{_plugin_set} to \c NULL.
1362 Plugin set of which to decrement the reference count.
1364 Can contain \c NULL.
1367 @bt_pre_assign_expr{_plugin_set}
1369 #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \
1371 bt_plugin_set_put_ref(_plugin_set); \
1372 (_plugin_set) = NULL; \
1377 Decrements the reference count of the plugin set \bt_p{_dst}, sets
1378 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1380 This macro effectively moves a plugin set reference from the expression
1381 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1382 \bt_p{_dst} reference.
1386 Destination expression.
1388 Can contain \c NULL.
1394 Can contain \c NULL.
1397 @bt_pre_assign_expr{_dst}
1398 @bt_pre_assign_expr{_src}
1400 #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \
1402 bt_plugin_set_put_ref(_dst); \
1415 #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */