1 #ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
2 #define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
33 #include <babeltrace2/types.h>
40 @defgroup api-plugin Plugin loading
43 Plugin loading functions.
45 A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls:
47 @image html plugin.png "A plugin is a package of component classes."
50 The plugin loading API offers functions to <em>find and load</em>
51 existing plugins and use the packaged \bt_p_comp_cls. To \em write a
52 plugin, see \ref api-plugin-dev.
54 There are three types of plugins:
57 <dt>Shared object plugin</dt>
59 <code>.so</code> file on Unix systems;
60 <code>.dll</code> file on Windows systems.
63 <dt>Python 3 plugin</dt>
65 <code>.py</code> file which starts with the
66 <code>bt_plugin_</code> prefix.
69 <dt>Static plugin</dt>
71 A plugin built directly into libbabeltrace2 or into the
76 libbabeltrace2 loads shared object and Python plugins. Those plugins
77 need libbabeltrace2 in turn to create and use \bt_name objects:
79 @image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
81 A plugin is a \ref api-fund-shared-object "shared object": get a new
82 reference with bt_plugin_get_ref() and put an existing reference with
85 Get the number of \bt_comp_cls in a plugin with
86 bt_plugin_get_source_component_class_count(),
87 bt_plugin_get_filter_component_class_count(), and
88 bt_plugin_get_sink_component_class_count().
90 Borrow a \bt_comp_cls by index from a plugin with
91 bt_plugin_borrow_source_component_class_by_index_const(),
92 bt_plugin_borrow_filter_component_class_by_index_const(), and
93 bt_plugin_borrow_sink_component_class_by_index_const().
95 Borrow a \bt_comp_cls by name from a plugin with
96 bt_plugin_borrow_source_component_class_by_name_const(),
97 bt_plugin_borrow_filter_component_class_by_name_const(), and
98 bt_plugin_borrow_sink_component_class_by_name_const().
100 The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
101 bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
102 functions return a <strong>plugin set</strong>, that is, a shared object
103 containing one or more plugins.
105 <h1>Find and load plugins</h1>
107 \anchor api-plugin-def-dirs The bt_plugin_find() and
108 bt_plugin_find_all() functions find and load plugins from the default
109 plugin search directories and from the static plugins.
111 The plugin search order is:
113 -# The colon-separated (or semicolon-separated on Windows) list of
114 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
117 The function searches each directory in this list, without recursing.
119 -# <code>$HOME/.local/lib/babeltrace2/plugins</code>,
122 -# The system \bt_name plugin directory, typically
123 <code>/usr/lib/babeltrace2/plugins</code> or
124 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux,
127 -# The static plugins.
129 Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
130 boolean parameters to include or exclude each of the four locations
133 <h2>Find and load a plugin by name</h2>
135 Find and load a plugin by name with bt_plugin_find().
137 bt_plugin_find() tries to find a plugin with a specific name within
138 the \ref api-plugin-def-dirs "default plugin search directories"
141 <h2>Find and load all the plugins from the default directories</h2>
143 Load all the plugins found in the
144 \ref api-plugin-def-dirs "default plugin search directories"
145 and static plugins with bt_plugin_find_all().
147 <h2>Find and load plugins from a specific file or directory</h2>
149 Find and load plugins from a specific file (<code>.so</code>,
150 <code>.dll</code>, or <code>.py</code>) with
151 bt_plugin_find_all_from_file().
153 A single shared object file can contain multiple plugins, although it's
154 not common practice to do so.
156 Find and load plugins from a specific directory with
157 bt_plugin_find_all_from_dir(). This function can search for plugins
158 within the given directory recursively or not.
160 <h2>Find and load static plugins</h2>
162 Find and load static plugins with bt_plugin_find_all_from_static().
164 A static plugin is built directly into the application or library
165 instead of being a separate shared object file.
167 <h1>Plugin properties</h1>
169 A plugin has the following properties:
173 \anchor api-plugin-prop-name
179 The plugin's name is not related to its file name. For example,
180 a plugin found in the file \c patente.so can be named
183 Use bt_plugin_get_name().
187 \anchor api-plugin-prop-descr
188 \bt_dt_opt Description
191 Description of the plugin.
193 Use bt_plugin_get_description().
197 \anchor api-plugin-prop-author
198 \bt_dt_opt Author name(s)
201 Name(s) of the plugin's author(s).
203 Use bt_plugin_get_author().
207 \anchor api-plugin-prop-license
211 License or license name of the plugin.
213 Use bt_plugin_get_license().
217 \anchor api-plugin-prop-path
221 Path of the file which contains the plugin.
223 A static plugin has no path property.
225 Get bt_plugin_get_path().
229 \anchor api-plugin-prop-version
233 Version of the plugin (major, minor, patch, and extra information).
235 The plugin's version is completely user-defined: the library does
236 not use this property in any way to verify the plugin's
239 Use bt_plugin_get_version().
250 @typedef struct bt_plugin bt_plugin;
256 @typedef struct bt_plugin_set bt_plugin_set;
265 @name Find and load plugins
271 Status codes for bt_plugin_find().
273 typedef enum bt_plugin_find_status
{
278 BT_PLUGIN_FIND_STATUS_OK
= __BT_FUNC_STATUS_OK
,
284 BT_PLUGIN_FIND_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
290 BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
296 BT_PLUGIN_FIND_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
297 } bt_plugin_find_status
;
301 Finds and loads a single plugin which has the name
302 \bt_p{plugin_name} from the default plugin search directories and
303 static plugins, setting \bt_p{*plugin} to the result.
305 This function returns the first plugin which has the name
306 \bt_p{plugin_name} within, in order:
308 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
310 the colon-separated (or semicolon-separated on Windows) list of
311 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
314 The function searches each directory in this list, without recursing.
316 -# <strong>If the \bt_p{find_in_user_dir} parameter is
317 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
320 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
321 system \bt_name plugin directory, typically
322 <code>/usr/lib/babeltrace2/plugins</code> or
323 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
326 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
330 A plugin's name is not related to the name of its file (shared
331 object or Python file). For example, a plugin found in the file
332 \c patente.so can be named <code>Dan</code>.
334 If this function finds a file which looks like a plugin (shared object
335 file or Python file with the \c bt_plugin_ prefix), but it fails to load
336 it for any reason, the function:
339 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
340 <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd>
342 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
343 <dd>Ignores the loading error and continues searching.</dd>
346 If this function doesn't find any plugin, it returns
347 #BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
349 @param[in] plugin_name
350 Name of the plugin to find and load.
351 @param[in] find_in_std_env_var
352 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
353 colon-separated (or semicolon-separated on Windows) list of
354 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
355 @param[in] find_in_user_dir
356 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
357 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
359 @param[in] find_in_sys_dir
360 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
361 the system \bt_name plugin directory.
362 @param[in] find_in_static
363 #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
365 @param[in] fail_on_load_error
366 #BT_TRUE to make this function return #BT_PLUGIN_FIND_STATUS_ERROR
367 on any plugin loading error instead of ignoring it.
369 <strong>On success</strong>, \bt_p{*plugin} is a new plugin
370 reference of named \bt_p{plugin_name}.
372 @retval #BT_PLUGIN_FIND_STATUS_OK
374 @retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND
376 @retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
378 @retval #BT_PLUGIN_FIND_STATUS_ERROR
381 @bt_pre_not_null{plugin_name}
383 At least one of the \bt_p{find_in_std_env_var},
384 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
385 \bt_p{find_in_static} parameters is #BT_TRUE.
386 @bt_pre_not_null{plugin}
388 @sa bt_plugin_find_all() —
389 Finds and loads all plugins from the default plugin search
390 directories and static plugins.
392 extern bt_plugin_find_status
bt_plugin_find(const char *plugin_name
,
393 bt_bool find_in_std_env_var
, bt_bool find_in_user_dir
,
394 bt_bool find_in_sys_dir
, bt_bool find_in_static
,
395 bt_bool fail_on_load_error
, const bt_plugin
**plugin
);
399 Status codes for bt_plugin_find_all().
401 typedef enum bt_plugin_find_all_status
{
406 BT_PLUGIN_FIND_ALL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
412 BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
418 BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
424 BT_PLUGIN_FIND_ALL_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
425 } bt_plugin_find_all_status
;
429 Finds and loads all the plugins from the default
430 plugin search directories and static plugins, setting
431 \bt_p{*plugins} to the result.
433 This function returns all the plugins within, in order:
435 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
437 the colon-separated (or semicolon-separated on Windows) list of
438 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
441 The function searches each directory in this list, without recursing.
443 -# <strong>If the \bt_p{find_in_user_dir} parameter is
444 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
447 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
448 system \bt_name plugin directory, typically
449 <code>/usr/lib/babeltrace2/plugins</code> or
450 <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
453 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
456 During the search process, if a found plugin shares the name of an
457 already loaded plugin, this function ignores it and continues.
459 If this function finds a file which looks like a plugin (shared object
460 file or Python file with the \c bt_plugin_ prefix), but it fails to load
461 it for any reason, the function:
464 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
465 <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
467 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
468 <dd>Ignores the loading error and continues searching.</dd>
471 If this function doesn't find any plugin, it returns
472 #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
475 @param[in] find_in_std_env_var
476 #BT_TRUE to try to find all the plugins in the
477 colon-separated (or semicolon-separated on Windows) list of
478 directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
479 @param[in] find_in_user_dir
480 #BT_TRUE to try to find all the plugins in
481 the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
483 @param[in] find_in_sys_dir
484 #BT_TRUE to try to find all the plugins in the system \bt_name
486 @param[in] find_in_static
487 #BT_TRUE to try to find all the plugins in the static plugins.
488 @param[in] fail_on_load_error
489 #BT_TRUE to make this function return
490 #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
493 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
494 reference which contains all the plugins found from the default
495 plugin search directories and static plugins.
497 @retval #BT_PLUGIN_FIND_ALL_STATUS_OK
499 @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
501 @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
503 @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
507 At least one of the \bt_p{find_in_std_env_var},
508 \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
509 \bt_p{find_in_static} parameters is #BT_TRUE.
510 @bt_pre_not_null{plugins}
512 @sa bt_plugin_find() —
513 Finds and loads a single plugin by name from the default plugin search
514 directories and static plugins.
516 bt_plugin_find_all_status
bt_plugin_find_all(bt_bool find_in_std_env_var
,
517 bt_bool find_in_user_dir
, bt_bool find_in_sys_dir
,
518 bt_bool find_in_static
, bt_bool fail_on_load_error
,
519 const bt_plugin_set
**plugins
);
523 Status codes for bt_plugin_find_all_from_file().
525 typedef enum bt_plugin_find_all_from_file_status
{
530 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
536 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
542 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
548 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
549 } bt_plugin_find_all_from_file_status
;
553 Finds and loads all the plugins from the file with path \bt_p{path},
554 setting \bt_p{*plugins} to the result.
557 A plugin's name is not related to the name of its file (shared
558 object or Python file). For example, a plugin found in the file
559 \c patente.so can be named <code>Dan</code>.
561 If any plugin loading error occurs during this function's execution, the
565 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
566 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
568 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
569 <dd>Ignores the loading error and continues.</dd>
572 If this function doesn't find any plugin, it returns
573 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
577 Path of the file in which to find and load all the plugins.
578 @param[in] fail_on_load_error
579 #BT_TRUE to make this function return
580 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
581 error instead of ignoring it.
583 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
584 reference which contains all the plugins found in the file with path
587 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
589 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
591 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
593 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
596 @bt_pre_not_null{path}
598 \bt_p{path} is the path of a regular file.
599 @bt_pre_not_null{plugins}
601 @sa bt_plugin_find_all_from_dir() —
602 Finds and loads all plugins from a given directory.
604 extern bt_plugin_find_all_from_file_status
bt_plugin_find_all_from_file(
605 const char *path
, bt_bool fail_on_load_error
,
606 const bt_plugin_set
**plugins
);
610 Status codes for bt_plugin_find_all_from_dir().
612 typedef enum bt_plugin_find_all_from_dir_status
{
617 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
623 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
629 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
635 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
636 } bt_plugin_find_all_from_dir_status
;
640 Finds and loads all the plugins from the directory with path
641 \bt_p{path}, setting \bt_p{*plugins} to the result.
643 If \bt_p{recurse} is #BT_TRUE, this function recurses into the
644 subdirectories of \bt_p{path} to find plugins.
646 During the search process, if a found plugin shares the name of an
647 already loaded plugin, this function ignores it and continues.
650 As of \bt_name_version_min_maj, the file and directory traversal
653 If any plugin loading error occurs during this function's execution, the
657 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
658 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
660 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
661 <dd>Ignores the loading error and continues.</dd>
664 If this function doesn't find any plugin, it returns
665 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
669 Path of the directory in which to find and load all the plugins.
671 #BT_TRUE to make this function recurse into the subdirectories
673 @param[in] fail_on_load_error
674 #BT_TRUE to make this function return
675 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
676 error instead of ignoring it.
678 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
679 reference which contains all the plugins found in the directory with
682 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
684 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
686 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
688 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
691 @bt_pre_not_null{path}
693 \bt_p{path} is the path of a directory.
694 @bt_pre_not_null{plugins}
696 @sa bt_plugin_find_all_from_file() —
697 Finds and loads all plugins from a given file.
699 extern bt_plugin_find_all_from_dir_status
bt_plugin_find_all_from_dir(
700 const char *path
, bt_bool recurse
, bt_bool fail_on_load_error
,
701 const bt_plugin_set
**plugins
);
705 Status codes for bt_plugin_find_all_from_static().
707 typedef enum bt_plugin_find_all_from_static_status
{
712 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
= __BT_FUNC_STATUS_OK
,
716 No static plugins found.
718 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
= __BT_FUNC_STATUS_NOT_FOUND
,
724 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
730 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
731 } bt_plugin_find_all_from_static_status
;
735 Finds and loads all the static plugins,
736 setting \bt_p{*plugins} to the result.
738 A static plugin is built directly into the application or library
739 instead of being a separate shared object file.
741 If any plugin loading error occurs during this function's execution, the
745 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
746 <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
748 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
749 <dd>Ignores the loading error and continues.</dd>
752 If this function doesn't find any plugin, it returns
753 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
756 @param[in] fail_on_load_error
757 #BT_TRUE to make this function return
758 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
759 error instead of ignoring it.
761 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
762 reference which contains all the static plugins.
764 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
766 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
767 No static plugins found.
768 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
770 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
773 @bt_pre_not_null{path}
774 @bt_pre_not_null{plugins}
776 extern bt_plugin_find_all_from_static_status
bt_plugin_find_all_from_static(
777 bt_bool fail_on_load_error
, const bt_plugin_set
**plugins
);
782 @name Plugin properties
788 Returns the name of the plugin \bt_p{plugin}.
790 See the \ref api-plugin-prop-name "name" property.
793 Plugin of which to get the name.
797 Name of \bt_p{plugin}.
799 The returned pointer remains valid as long as \bt_p{plugin} exists.
802 @bt_pre_not_null{plugin}
804 extern const char *bt_plugin_get_name(const bt_plugin
*plugin
);
808 Returns the description of the plugin \bt_p{plugin}.
810 See the \ref api-plugin-prop-descr "description" property.
813 Plugin of which to get description.
817 Description of \bt_p{plugin}, or \c NULL if not available.
819 The returned pointer remains valid as long as \bt_p{plugin} exists.
822 @bt_pre_not_null{plugin}
824 extern const char *bt_plugin_get_description(const bt_plugin
*plugin
);
828 Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
830 See the \ref api-plugin-prop-author "author name(s)" property.
833 Plugin of which to get the author name(s).
837 Author name(s) of \bt_p{plugin}, or \c NULL if not available.
839 The returned pointer remains valid as long as \bt_p{plugin} exists.
842 @bt_pre_not_null{plugin}
844 extern const char *bt_plugin_get_author(const bt_plugin
*plugin
);
848 Returns the license text or the license name of the plugin
851 See the \ref api-plugin-prop-license "license" property.
854 Plugin of which to get the license.
858 License of \bt_p{plugin}, or \c NULL if not available.
860 The returned pointer remains valid as long as \bt_p{plugin} exists.
863 @bt_pre_not_null{plugin}
865 extern const char *bt_plugin_get_license(const bt_plugin
*plugin
);
869 Returns the path of the file which contains the plugin
872 See the \ref api-plugin-prop-path "path" property.
874 This function returns \c NULL if \bt_p{plugin} is a static plugin
875 because a static plugin has no path property.
878 Plugin of which to get the containing file's path.
882 Path of the file which contains \bt_p{plugin}, or \c NULL if
885 The returned pointer remains valid as long as \bt_p{plugin} exists.
888 @bt_pre_not_null{plugin}
890 extern const char *bt_plugin_get_path(const bt_plugin
*plugin
);
894 Returns the version of the plugin \bt_p{plugin}.
896 See the \ref api-plugin-prop-version "version" property.
899 Plugin of which to get the version.
901 <strong>If not \c NULL and this function returns
902 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
903 major version of \bt_p{plugin}.
905 <strong>If not \c NULL and this function returns
906 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
907 minor version of \bt_p{plugin}.
909 <strong>If not \c NULL and this function returns
910 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
911 patch version of \bt_p{plugin}.
914 <strong>If not \c NULL and this function returns
915 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
916 version's extra information of \bt_p{plugin}.
918 \bt_p{*extra} can be \c NULL if the plugin's version has no extra
921 \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
924 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
925 The version of \bt_p{plugin} is available.
926 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
927 The version of \bt_p{plugin} is not available.
929 @bt_pre_not_null{plugin}
931 extern bt_property_availability
bt_plugin_get_version(
932 const bt_plugin
*plugin
, unsigned int *major
,
933 unsigned int *minor
, unsigned int *patch
, const char **extra
);
938 @name Plugin component class access
944 Returns the number of source component classes contained in the
945 plugin \bt_p{plugin}.
948 Plugin of which to get the number of contained source
952 Number of contained source component classes in \bt_p{plugin}.
954 @bt_pre_not_null{plugin}
956 extern uint64_t bt_plugin_get_source_component_class_count(
957 const bt_plugin
*plugin
);
961 Returns the number of filter component classes contained in the
962 plugin \bt_p{plugin}.
965 Plugin of which to get the number of contained filter
969 Number of contained filter component classes in \bt_p{plugin}.
971 @bt_pre_not_null{plugin}
973 extern uint64_t bt_plugin_get_filter_component_class_count(
974 const bt_plugin
*plugin
);
978 Returns the number of sink component classes contained in the
979 plugin \bt_p{plugin}.
982 Plugin of which to get the number of contained sink
986 Number of contained sink component classes in \bt_p{plugin}.
988 @bt_pre_not_null{plugin}
990 extern uint64_t bt_plugin_get_sink_component_class_count(
991 const bt_plugin
*plugin
);
995 Borrows the source component class at index \bt_p{index} from the
996 plugin \bt_p{plugin}.
999 Plugin from which to borrow the source component class at index
1002 Index of the source component class to borrow from \bt_p{plugin}.
1006 \em Borrowed reference of the source component class of
1007 \bt_p{plugin} at index \bt_p{index}.
1009 The returned pointer remains valid as long as \bt_p{plugin} exists.
1012 @bt_pre_not_null{plugin}
1014 \bt_p{index} is less than the number of source component classes in
1015 \bt_p{plugin} (as returned by
1016 bt_plugin_get_source_component_class_count()).
1018 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1019 Borrows a source component class by name from a plugin.
1021 extern const bt_component_class_source
*
1022 bt_plugin_borrow_source_component_class_by_index_const(
1023 const bt_plugin
*plugin
, uint64_t index
);
1027 Borrows the filter component class at index \bt_p{index} from the
1028 plugin \bt_p{plugin}.
1031 Plugin from which to borrow the filter component class at index
1034 Index of the filter component class to borrow from \bt_p{plugin}.
1038 \em Borrowed reference of the filter component class of
1039 \bt_p{plugin} at index \bt_p{index}.
1041 The returned pointer remains valid as long as \bt_p{plugin} exists.
1044 @bt_pre_not_null{plugin}
1046 \bt_p{index} is less than the number of filter component classes in
1047 \bt_p{plugin} (as returned by
1048 bt_plugin_get_source_component_class_count()).
1050 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1051 Borrows a filter component class by name from a plugin.
1053 extern const bt_component_class_filter
*
1054 bt_plugin_borrow_filter_component_class_by_index_const(
1055 const bt_plugin
*plugin
, uint64_t index
);
1059 Borrows the sink component class at index \bt_p{index} from the
1060 plugin \bt_p{plugin}.
1063 Plugin from which to borrow the sink component class at index
1066 Index of the sink component class to borrow from \bt_p{plugin}.
1070 \em Borrowed reference of the sink component class of
1071 \bt_p{plugin} at index \bt_p{index}.
1073 The returned pointer remains valid as long as \bt_p{plugin} exists.
1076 @bt_pre_not_null{plugin}
1078 \bt_p{index} is less than the number of sink component classes in
1079 \bt_p{plugin} (as returned by
1080 bt_plugin_get_source_component_class_count()).
1082 @sa bt_plugin_borrow_source_component_class_by_name_const() —
1083 Borrows a sink component class by name from a plugin.
1085 extern const bt_component_class_sink
*
1086 bt_plugin_borrow_sink_component_class_by_index_const(
1087 const bt_plugin
*plugin
, uint64_t index
);
1091 Borrows the source component class named \bt_p{name} from the
1092 plugin \bt_p{plugin}.
1094 If no source component class has the name \bt_p{name} within
1095 \bt_p{plugin}, this function returns \c NULL.
1098 Plugin from which to borrow the source component class named
1101 Name of the source component class to borrow from \bt_p{plugin}.
1105 \em Borrowed reference of the source component class of
1106 \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
1107 class is named \bt_p{name} within \bt_p{plugin}.
1109 The returned pointer remains valid as long as \bt_p{plugin} exists.
1112 @bt_pre_not_null{plugin}
1113 @bt_pre_not_null{name}
1115 @sa bt_plugin_borrow_source_component_class_by_index_const() —
1116 Borrows a source component class by index from a plugin.
1118 extern const bt_component_class_source
*
1119 bt_plugin_borrow_source_component_class_by_name_const(
1120 const bt_plugin
*plugin
, const char *name
);
1124 Borrows the filter component class named \bt_p{name} from the
1125 plugin \bt_p{plugin}.
1127 If no filter component class has the name \bt_p{name} within
1128 \bt_p{plugin}, this function returns \c NULL.
1131 Plugin from which to borrow the filter component class named
1134 Name of the filter component class to borrow from \bt_p{plugin}.
1138 \em Borrowed reference of the filter component class of
1139 \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
1140 class is named \bt_p{name} within \bt_p{plugin}.
1142 The returned pointer remains valid as long as \bt_p{plugin} exists.
1145 @bt_pre_not_null{plugin}
1146 @bt_pre_not_null{name}
1148 @sa bt_plugin_borrow_filter_component_class_by_index_const() —
1149 Borrows a filter component class by index from a plugin.
1151 extern const bt_component_class_filter
*
1152 bt_plugin_borrow_filter_component_class_by_name_const(
1153 const bt_plugin
*plugin
, const char *name
);
1157 Borrows the sink component class named \bt_p{name} from the
1158 plugin \bt_p{plugin}.
1160 If no sink component class has the name \bt_p{name} within
1161 \bt_p{plugin}, this function returns \c NULL.
1164 Plugin from which to borrow the sink component class named
1167 Name of the sink component class to borrow from \bt_p{plugin}.
1171 \em Borrowed reference of the sink component class of
1172 \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
1173 class is named \bt_p{name} within \bt_p{plugin}.
1175 The returned pointer remains valid as long as \bt_p{plugin} exists.
1178 @bt_pre_not_null{plugin}
1179 @bt_pre_not_null{name}
1181 @sa bt_plugin_borrow_sink_component_class_by_index_const() —
1182 Borrows a sink component class by index from a plugin.
1184 extern const bt_component_class_sink
*
1185 bt_plugin_borrow_sink_component_class_by_name_const(
1186 const bt_plugin
*plugin
, const char *name
);
1191 @name Plugin reference count
1197 Increments the \ref api-fund-shared-object "reference count" of
1198 the plugin \bt_p{plugin}.
1202 Plugin of which to increment the reference count.
1207 @sa bt_plugin_put_ref() —
1208 Decrements the reference count of a plugin.
1210 extern void bt_plugin_get_ref(const bt_plugin
*plugin
);
1214 Decrements the \ref api-fund-shared-object "reference count" of
1215 the plugin \bt_p{plugin}.
1219 Plugin of which to decrement the reference count.
1224 @sa bt_plugin_get_ref() —
1225 Increments the reference count of a plugin.
1227 extern void bt_plugin_put_ref(const bt_plugin
*plugin
);
1231 Decrements the reference count of the plugin \bt_p{_plugin}, and
1232 then sets \bt_p{_plugin} to \c NULL.
1236 Plugin of which to decrement the reference count.
1238 Can contain \c NULL.
1241 @bt_pre_assign_expr{_plugin}
1243 #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \
1245 bt_plugin_put_ref(_plugin); \
1251 Decrements the reference count of the plugin \bt_p{_dst}, sets
1252 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1254 This macro effectively moves a plugin reference from the expression
1255 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1256 \bt_p{_dst} reference.
1260 Destination expression.
1262 Can contain \c NULL.
1268 Can contain \c NULL.
1271 @bt_pre_assign_expr{_dst}
1272 @bt_pre_assign_expr{_src}
1274 #define BT_PLUGIN_MOVE_REF(_dst, _src) \
1276 bt_plugin_put_ref(_dst); \
1284 @name Plugin set plugin access
1290 Returns the number of plugins contained in the
1291 plugin set \bt_p{plugin_set}.
1293 @param[in] plugin_set
1294 Plugin set of which to get the number of contained plugins.
1297 Number of contained plugins in \bt_p{plugin_set}.
1299 @bt_pre_not_null{plugin}
1301 extern uint64_t bt_plugin_set_get_plugin_count(
1302 const bt_plugin_set
*plugin_set
);
1306 Borrows the plugin at index \bt_p{index} from the plugin set
1309 @param[in] plugin_set
1310 Plugin set from which to borrow the plugin at index \bt_p{index}.
1312 Index of the plugin to borrow from \bt_p{plugin_set}.
1316 \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1319 The returned pointer remains valid until \bt_p{plugin_set} is
1323 @bt_pre_not_null{plugin_set}
1325 \bt_p{index} is less than the number of plugins in
1326 \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
1328 extern const bt_plugin
*bt_plugin_set_borrow_plugin_by_index_const(
1329 const bt_plugin_set
*plugin_set
, uint64_t index
);
1334 @name Plugin set reference count
1340 Increments 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 increment the reference count.
1350 @sa bt_plugin_set_put_ref() —
1351 Decrements the reference count of a plugin set.
1353 extern void bt_plugin_set_get_ref(const bt_plugin_set
*plugin_set
);
1357 Decrements the \ref api-fund-shared-object "reference count" of
1358 the plugin set \bt_p{plugin_set}.
1360 @param[in] plugin_set
1362 Plugin set of which to decrement the reference count.
1367 @sa bt_plugin_set_get_ref() —
1368 Increments the reference count of a plugin set.
1370 extern void bt_plugin_set_put_ref(const bt_plugin_set
*plugin_set
);
1374 Decrements the reference count of the plugin set \bt_p{_plugin_set},
1375 and then sets \bt_p{_plugin_set} to \c NULL.
1379 Plugin set of which to decrement the reference count.
1381 Can contain \c NULL.
1384 @bt_pre_assign_expr{_plugin_set}
1386 #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \
1388 bt_plugin_set_put_ref(_plugin_set); \
1389 (_plugin_set) = NULL; \
1394 Decrements the reference count of the plugin set \bt_p{_dst}, sets
1395 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1397 This macro effectively moves a plugin set reference from the expression
1398 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1399 \bt_p{_dst} reference.
1403 Destination expression.
1405 Can contain \c NULL.
1411 Can contain \c NULL.
1414 @bt_pre_assign_expr{_dst}
1415 @bt_pre_assign_expr{_src}
1417 #define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \
1419 bt_plugin_set_put_ref(_dst); \
1432 #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */