include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / plugin / plugin-loading.h
CommitLineData
43c59509 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
43c59509 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
43c59509
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
8#define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
43c59509
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
16#include <stdint.h>
17#include <stddef.h>
18
19#include <babeltrace2/types.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/*!
26@defgroup api-plugin Plugin loading
27
28@brief
29 Plugin loading functions.
30
31A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls:
32
33@image html plugin.png "A plugin is a package of component classes."
34
35@attention
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.
39
40There are three types of plugins:
41
42<dl>
43 <dt>Shared object plugin</dt>
44 <dd>
45 <code>.so</code> file on Unix systems;
46 <code>.dll</code> file on Windows systems.
47 </dd>
48
49 <dt>Python&nbsp;3 plugin</dt>
50 <dd>
51 <code>.py</code> file which starts with the
52 <code>bt_plugin_</code> prefix.
53 </dd>
54
55 <dt>Static plugin</dt>
56 <dd>
57 A plugin built directly into libbabeltrace2 or into the
58 user application.
59 </dd>
60</dl>
61
62libbabeltrace2 loads shared object and Python plugins. Those plugins
63need libbabeltrace2 in turn to create and use \bt_name objects:
64
65@image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
66
67A plugin is a \ref api-fund-shared-object "shared object": get a new
68reference with bt_plugin_get_ref() and put an existing reference with
69bt_plugin_put_ref().
70
71Get the number of \bt_comp_cls in a plugin with
72bt_plugin_get_source_component_class_count(),
73bt_plugin_get_filter_component_class_count(), and
74bt_plugin_get_sink_component_class_count().
75
76Borrow a \bt_comp_cls by index from a plugin with
77bt_plugin_borrow_source_component_class_by_index_const(),
78bt_plugin_borrow_filter_component_class_by_index_const(), and
79bt_plugin_borrow_sink_component_class_by_index_const().
80
81Borrow a \bt_comp_cls by name from a plugin with
82bt_plugin_borrow_source_component_class_by_name_const(),
83bt_plugin_borrow_filter_component_class_by_name_const(), and
84bt_plugin_borrow_sink_component_class_by_name_const().
85
86The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
87bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
88functions return a <strong>plugin set</strong>, that is, a shared object
89containing one or more plugins.
90
91<h1>Find and load plugins</h1>
92
93\anchor api-plugin-def-dirs The bt_plugin_find() and
94bt_plugin_find_all() functions find and load plugins from the default
95plugin search directories and from the static plugins.
96
97The plugin search order is:
98
99-# The colon-separated (or semicolon-separated on Windows) list of
100 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
101 if it's set.
102
103 The function searches each directory in this list, without recursing.
104
105-# <code>$HOME/.local/lib/babeltrace2/plugins</code>,
106 without recursing.
107
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,
111 without recursing.
112
113-# The static plugins.
114
115Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
116boolean parameters to include or exclude each of the four locations
117above.
118
119<h2>Find and load a plugin by name</h2>
120
121Find and load a plugin by name with bt_plugin_find().
122
123bt_plugin_find() tries to find a plugin with a specific name within
124the \ref api-plugin-def-dirs "default plugin search directories"
125and static plugins.
126
127<h2>Find and load all the plugins from the default directories</h2>
128
129Load all the plugins found in the
130\ref api-plugin-def-dirs "default plugin search directories"
131and static plugins with bt_plugin_find_all().
132
133<h2>Find and load plugins from a specific file or directory</h2>
134
135Find and load plugins from a specific file (<code>.so</code>,
136<code>.dll</code>, or <code>.py</code>) with
137bt_plugin_find_all_from_file().
138
139A single shared object file can contain multiple plugins, although it's
140not common practice to do so.
141
142Find and load plugins from a specific directory with
143bt_plugin_find_all_from_dir(). This function can search for plugins
144within the given directory recursively or not.
145
146<h2>Find and load static plugins</h2>
147
148Find and load static plugins with bt_plugin_find_all_from_static().
149
150A static plugin is built directly into the application or library
151instead of being a separate shared object file.
152
153<h1>Plugin properties</h1>
154
155A plugin has the following properties:
156
157<dl>
158 <dt>
159 \anchor api-plugin-prop-name
160 Name
161 </dt>
162 <dd>
163 Name of the plugin.
164
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
167 <code>Dan</code>.
168
169 Use bt_plugin_get_name().
170 </dd>
171
172 <dt>
173 \anchor api-plugin-prop-descr
174 \bt_dt_opt Description
175 </dt>
176 <dd>
177 Description of the plugin.
178
179 Use bt_plugin_get_description().
180 </dd>
181
182 <dt>
183 \anchor api-plugin-prop-author
184 \bt_dt_opt Author name(s)
185 </dt>
186 <dd>
187 Name(s) of the plugin's author(s).
188
189 Use bt_plugin_get_author().
190 </dd>
191
192 <dt>
193 \anchor api-plugin-prop-license
194 \bt_dt_opt License
195 </dt>
196 <dd>
197 License or license name of the plugin.
198
199 Use bt_plugin_get_license().
200 </dd>
201
202 <dt>
203 \anchor api-plugin-prop-path
204 \bt_dt_opt Path
205 </dt>
206 <dd>
207 Path of the file which contains the plugin.
208
209 A static plugin has no path property.
210
211 Get bt_plugin_get_path().
212 </dd>
213
214 <dt>
215 \anchor api-plugin-prop-version
216 \bt_dt_opt Version
217 </dt>
218 <dd>
219 Version of the plugin (major, minor, patch, and extra information).
220
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
223 compatibility.
224
225 Use bt_plugin_get_version().
226 </dd>
227</dl>
228*/
229
230/*! @{ */
231
232/*!
233@name Type
234@{
235
236@typedef struct bt_plugin bt_plugin;
237
238@brief
239 Plugin.
240
43c59509
PP
241@typedef struct bt_plugin_set bt_plugin_set;
242
243@brief
244 Set of plugins.
245
246@}
247*/
248
249/*!
250@name Find and load plugins
251@{
252*/
253
254/*!
255@brief
256 Status codes for bt_plugin_find().
257*/
258typedef enum bt_plugin_find_status {
259 /*!
260 @brief
261 Success.
262 */
263 BT_PLUGIN_FIND_STATUS_OK = __BT_FUNC_STATUS_OK,
264
265 /*!
266 @brief
267 Plugin not found.
268 */
269 BT_PLUGIN_FIND_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND,
270
271 /*!
272 @brief
273 Out of memory.
274 */
275 BT_PLUGIN_FIND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
276
277 /*!
278 @brief
279 Error.
280 */
281 BT_PLUGIN_FIND_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
282} bt_plugin_find_status;
283
284/*!
285@brief
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.
289
290This function returns the first plugin which has the name
291\bt_p{plugin_name} within, in order:
292
293-# <strong>If the \bt_p{find_in_std_env_var} parameter is
294 #BT_TRUE</strong>,
295 the colon-separated (or semicolon-separated on Windows) list of
296 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
297 if it's set.
298
299 The function searches each directory in this list, without recursing.
300
301-# <strong>If the \bt_p{find_in_user_dir} parameter is
302 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
303 without recursing.
304
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
309 recursing.
310
311-# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
312 the static plugins.
313
314@note
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>.
318
319If this function finds a file which looks like a plugin (shared object
320file or Python file with the \c bt_plugin_ prefix), but it fails to load
321it for any reason, the function:
322
323<dl>
324 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
325 <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd>
326
327 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
328 <dd>Ignores the loading error and continues searching.</dd>
329</dl>
330
331If this function doesn't find any plugin, it returns
332#BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
333
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,
343 without recursing.
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
349 static plugins.
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.
353@param[out] plugin
354 <strong>On success</strong>, \bt_p{*plugin} is a new plugin
355 reference of named \bt_p{plugin_name}.
356
357@retval #BT_PLUGIN_FIND_STATUS_OK
358 Success.
359@retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND
360 Plugin not found.
361@retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
362 Out of memory.
363@retval #BT_PLUGIN_FIND_STATUS_ERROR
364 Error.
365
366@bt_pre_not_null{plugin_name}
367@pre
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}
372
373@sa bt_plugin_find_all() &mdash;
374 Finds and loads all plugins from the default plugin search
375 directories and static plugins.
376*/
377extern 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);
381
382/*!
383@brief
384 Status codes for bt_plugin_find_all().
385*/
386typedef enum bt_plugin_find_all_status {
387 /*!
388 @brief
389 Success.
390 */
391 BT_PLUGIN_FIND_ALL_STATUS_OK = __BT_FUNC_STATUS_OK,
392
393 /*!
394 @brief
395 No plugins found.
396 */
397 BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND,
398
399 /*!
400 @brief
401 Out of memory.
402 */
403 BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
404
405 /*!
406 @brief
407 Error.
408 */
409 BT_PLUGIN_FIND_ALL_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
410} bt_plugin_find_all_status;
411
412/*!
413@brief
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.
417
418This function returns all the plugins within, in order:
419
420-# <strong>If the \bt_p{find_in_std_env_var} parameter is
421 #BT_TRUE</strong>,
422 the colon-separated (or semicolon-separated on Windows) list of
423 directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
424 if it's set.
425
426 The function searches each directory in this list, without recursing.
427
428-# <strong>If the \bt_p{find_in_user_dir} parameter is
429 #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
430 without recursing.
431
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
436 recursing.
437
438-# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
439 the static plugins.
440
441During the search process, if a found plugin shares the name of an
442already loaded plugin, this function ignores it and continues.
443
444If this function finds a file which looks like a plugin (shared object
445file or Python file with the \c bt_plugin_ prefix), but it fails to load
446it for any reason, the function:
447
448<dl>
449 <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
450 <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
451
452 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
453 <dd>Ignores the loading error and continues searching.</dd>
454</dl>
455
456If this function doesn't find any plugin, it returns
457#BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
458\bt_p{*plugins}.
459
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,
467 without recursing.
468@param[in] find_in_sys_dir
469 #BT_TRUE to try to find all the plugins in the system \bt_name
470 plugin directory.
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
476 of ignoring it.
477@param[out] plugins
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.
481
482@retval #BT_PLUGIN_FIND_ALL_STATUS_OK
483 Success.
484@retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
485 No plugins found.
486@retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
487 Out of memory.
488@retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
489 Error.
490
491@pre
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}
496
497@sa bt_plugin_find() &mdash;
498 Finds and loads a single plugin by name from the default plugin search
499 directories and static plugins.
500*/
501bt_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);
505
506/*!
507@brief
508 Status codes for bt_plugin_find_all_from_file().
509*/
510typedef enum bt_plugin_find_all_from_file_status {
511 /*!
512 @brief
513 Success.
514 */
515 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK = __BT_FUNC_STATUS_OK,
516
517 /*!
518 @brief
519 No plugins found.
520 */
521 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND,
522
523 /*!
524 @brief
525 Out of memory.
526 */
527 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
528
529 /*!
530 @brief
531 Error.
532 */
533 BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
534} bt_plugin_find_all_from_file_status;
535
536/*!
537@brief
538 Finds and loads all the plugins from the file with path \bt_p{path},
539 setting \bt_p{*plugins} to the result.
540
541@note
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>.
545
546If any plugin loading error occurs during this function's execution, the
547function:
548
549<dl>
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>
552
553 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
554 <dd>Ignores the loading error and continues.</dd>
555</dl>
556
557If this function doesn't find any plugin, it returns
558#BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
559\bt_p{*plugins}.
560
561@param[in] path
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.
567@param[out] plugins
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
570 \bt_p{path}.
571
572@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
573 Success.
574@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
575 No plugins found.
576@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
577 Out of memory.
578@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
579 Error.
580
581@bt_pre_not_null{path}
582@pre
583 \bt_p{path} is the path of a regular file.
584@bt_pre_not_null{plugins}
585
586@sa bt_plugin_find_all_from_dir() &mdash;
587 Finds and loads all plugins from a given directory.
588*/
589extern 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);
592
593/*!
594@brief
595 Status codes for bt_plugin_find_all_from_dir().
596*/
597typedef enum bt_plugin_find_all_from_dir_status {
598 /*!
599 @brief
600 Success.
601 */
602 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK = __BT_FUNC_STATUS_OK,
603
604 /*!
605 @brief
606 No plugins found.
607 */
608 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND,
609
610 /*!
611 @brief
612 Out of memory.
613 */
614 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
615
616 /*!
617 @brief
618 Error.
619 */
620 BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
621} bt_plugin_find_all_from_dir_status;
622
623/*!
624@brief
625 Finds and loads all the plugins from the directory with path
626 \bt_p{path}, setting \bt_p{*plugins} to the result.
627
628If \bt_p{recurse} is #BT_TRUE, this function recurses into the
629subdirectories of \bt_p{path} to find plugins.
630
631During the search process, if a found plugin shares the name of an
632already loaded plugin, this function ignores it and continues.
633
634@attention
635 As of \bt_name_version_min_maj, the file and directory traversal
636 order is undefined.
637
638If any plugin loading error occurs during this function's execution, the
639function:
640
641<dl>
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>
644
645 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
646 <dd>Ignores the loading error and continues.</dd>
647</dl>
648
649If this function doesn't find any plugin, it returns
650#BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
651\bt_p{*plugins}.
652
653@param[in] path
654 Path of the directory in which to find and load all the plugins.
655@param[in] recurse
656 #BT_TRUE to make this function recurse into the subdirectories
657 of \bt_p{path}.
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.
662@param[out] plugins
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
665 path \bt_p{path}.
666
667@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
668 Success.
669@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
670 No plugins found.
671@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
672 Out of memory.
673@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
674 Error.
675
676@bt_pre_not_null{path}
677@pre
678 \bt_p{path} is the path of a directory.
679@bt_pre_not_null{plugins}
680
681@sa bt_plugin_find_all_from_file() &mdash;
682 Finds and loads all plugins from a given file.
683*/
684extern 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);
687
688/*!
689@brief
690 Status codes for bt_plugin_find_all_from_static().
691*/
692typedef enum bt_plugin_find_all_from_static_status {
693 /*!
694 @brief
695 Success.
696 */
697 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK = __BT_FUNC_STATUS_OK,
698
699 /*!
700 @brief
701 No static plugins found.
702 */
703 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND,
704
705 /*!
706 @brief
707 Out of memory.
708 */
709 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
710
711 /*!
712 @brief
713 Error.
714 */
715 BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
716} bt_plugin_find_all_from_static_status;
717
718/*!
719@brief
720 Finds and loads all the static plugins,
721 setting \bt_p{*plugins} to the result.
722
723A static plugin is built directly into the application or library
724instead of being a separate shared object file.
725
726If any plugin loading error occurs during this function's execution, the
727function:
728
729<dl>
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>
732
733 <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
734 <dd>Ignores the loading error and continues.</dd>
735</dl>
736
737If this function doesn't find any plugin, it returns
738#BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
739\bt_p{*plugins}.
740
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.
745@param[out] plugins
746 <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
747 reference which contains all the static plugins.
748
749@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
750 Success.
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
754 Out of memory.
755@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
756 Error.
757
758@bt_pre_not_null{path}
759@bt_pre_not_null{plugins}
760*/
761extern 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);
763
764/*! @} */
765
766/*!
767@name Plugin properties
768@{
769*/
770
771/*!
772@brief
773 Returns the name of the plugin \bt_p{plugin}.
774
775See the \ref api-plugin-prop-name "name" property.
776
777@param[in] plugin
778 Plugin of which to get the name.
779
780@returns
781 @parblock
782 Name of \bt_p{plugin}.
783
784 The returned pointer remains valid as long as \bt_p{plugin} exists.
785 @endparblock
786
787@bt_pre_not_null{plugin}
788*/
789extern const char *bt_plugin_get_name(const bt_plugin *plugin);
790
791/*!
792@brief
793 Returns the description of the plugin \bt_p{plugin}.
794
795See the \ref api-plugin-prop-descr "description" property.
796
797@param[in] plugin
798 Plugin of which to get description.
799
800@returns
801 @parblock
802 Description of \bt_p{plugin}, or \c NULL if not available.
803
804 The returned pointer remains valid as long as \bt_p{plugin} exists.
805 @endparblock
806
807@bt_pre_not_null{plugin}
808*/
809extern const char *bt_plugin_get_description(const bt_plugin *plugin);
810
811/*!
812@brief
813 Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
814
815See the \ref api-plugin-prop-author "author name(s)" property.
816
817@param[in] plugin
818 Plugin of which to get the author name(s).
819
820@returns
821 @parblock
822 Author name(s) of \bt_p{plugin}, or \c NULL if not available.
823
824 The returned pointer remains valid as long as \bt_p{plugin} exists.
825 @endparblock
826
827@bt_pre_not_null{plugin}
828*/
829extern const char *bt_plugin_get_author(const bt_plugin *plugin);
830
831/*!
832@brief
833 Returns the license text or the license name of the plugin
834 \bt_p{plugin}.
835
836See the \ref api-plugin-prop-license "license" property.
837
838@param[in] plugin
839 Plugin of which to get the license.
840
841@returns
842 @parblock
843 License of \bt_p{plugin}, or \c NULL if not available.
844
845 The returned pointer remains valid as long as \bt_p{plugin} exists.
846 @endparblock
847
848@bt_pre_not_null{plugin}
849*/
850extern const char *bt_plugin_get_license(const bt_plugin *plugin);
851
852/*!
853@brief
854 Returns the path of the file which contains the plugin
855 \bt_p{plugin}.
856
857See the \ref api-plugin-prop-path "path" property.
858
859This function returns \c NULL if \bt_p{plugin} is a static plugin
860because a static plugin has no path property.
861
862@param[in] plugin
863 Plugin of which to get the containing file's path.
864
865@returns
866 @parblock
867 Path of the file which contains \bt_p{plugin}, or \c NULL if
868 not available.
869
870 The returned pointer remains valid as long as \bt_p{plugin} exists.
871 @endparblock
872
873@bt_pre_not_null{plugin}
874*/
875extern const char *bt_plugin_get_path(const bt_plugin *plugin);
876
877/*!
878@brief
879 Returns the version of the plugin \bt_p{plugin}.
880
881See the \ref api-plugin-prop-version "version" property.
882
883@param[in] plugin
884 Plugin of which to get the version.
885@param[out] major
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}.
889@param[out] minor
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}.
893@param[out] patch
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}.
897@param[out] extra
898 @parblock
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}.
902
903 \bt_p{*extra} can be \c NULL if the plugin's version has no extra
904 information.
905
906 \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
907 @endparblock
908
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.
913
914@bt_pre_not_null{plugin}
915*/
916extern 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);
919
920/*! @} */
921
922/*!
923@name Plugin component class access
924@{
925*/
926
927/*!
928@brief
929 Returns the number of source component classes contained in the
930 plugin \bt_p{plugin}.
931
932@param[in] plugin
933 Plugin of which to get the number of contained source
934 component classes.
935
936@returns
937 Number of contained source component classes in \bt_p{plugin}.
938
939@bt_pre_not_null{plugin}
940*/
941extern uint64_t bt_plugin_get_source_component_class_count(
942 const bt_plugin *plugin);
943
944/*!
945@brief
946 Returns the number of filter component classes contained in the
947 plugin \bt_p{plugin}.
948
949@param[in] plugin
950 Plugin of which to get the number of contained filter
951 component classes.
952
953@returns
954 Number of contained filter component classes in \bt_p{plugin}.
955
956@bt_pre_not_null{plugin}
957*/
958extern uint64_t bt_plugin_get_filter_component_class_count(
959 const bt_plugin *plugin);
960
961/*!
962@brief
963 Returns the number of sink component classes contained in the
964 plugin \bt_p{plugin}.
965
966@param[in] plugin
967 Plugin of which to get the number of contained sink
968 component classes.
969
970@returns
971 Number of contained sink component classes in \bt_p{plugin}.
972
973@bt_pre_not_null{plugin}
974*/
975extern uint64_t bt_plugin_get_sink_component_class_count(
976 const bt_plugin *plugin);
977
978/*!
979@brief
980 Borrows the source component class at index \bt_p{index} from the
981 plugin \bt_p{plugin}.
982
983@param[in] plugin
984 Plugin from which to borrow the source component class at index
985 \bt_p{index}.
986@param[in] index
987 Index of the source component class to borrow from \bt_p{plugin}.
988
989@returns
990 @parblock
991 \em Borrowed reference of the source component class of
992 \bt_p{plugin} at index \bt_p{index}.
993
994 The returned pointer remains valid as long as \bt_p{plugin} exists.
995 @endparblock
996
997@bt_pre_not_null{plugin}
998@pre
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()).
1002
1003@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1004 Borrows a source component class by name from a plugin.
1005*/
1006extern const bt_component_class_source *
1007bt_plugin_borrow_source_component_class_by_index_const(
1008 const bt_plugin *plugin, uint64_t index);
1009
1010/*!
1011@brief
1012 Borrows the filter component class at index \bt_p{index} from the
1013 plugin \bt_p{plugin}.
1014
1015@param[in] plugin
1016 Plugin from which to borrow the filter component class at index
1017 \bt_p{index}.
1018@param[in] index
1019 Index of the filter component class to borrow from \bt_p{plugin}.
1020
1021@returns
1022 @parblock
1023 \em Borrowed reference of the filter component class of
1024 \bt_p{plugin} at index \bt_p{index}.
1025
1026 The returned pointer remains valid as long as \bt_p{plugin} exists.
1027 @endparblock
1028
1029@bt_pre_not_null{plugin}
1030@pre
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()).
1034
1035@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1036 Borrows a filter component class by name from a plugin.
1037*/
1038extern const bt_component_class_filter *
1039bt_plugin_borrow_filter_component_class_by_index_const(
1040 const bt_plugin *plugin, uint64_t index);
1041
1042/*!
1043@brief
1044 Borrows the sink component class at index \bt_p{index} from the
1045 plugin \bt_p{plugin}.
1046
1047@param[in] plugin
1048 Plugin from which to borrow the sink component class at index
1049 \bt_p{index}.
1050@param[in] index
1051 Index of the sink component class to borrow from \bt_p{plugin}.
1052
1053@returns
1054 @parblock
1055 \em Borrowed reference of the sink component class of
1056 \bt_p{plugin} at index \bt_p{index}.
1057
1058 The returned pointer remains valid as long as \bt_p{plugin} exists.
1059 @endparblock
1060
1061@bt_pre_not_null{plugin}
1062@pre
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()).
1066
1067@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1068 Borrows a sink component class by name from a plugin.
1069*/
1070extern const bt_component_class_sink *
1071bt_plugin_borrow_sink_component_class_by_index_const(
1072 const bt_plugin *plugin, uint64_t index);
1073
1074/*!
1075@brief
1076 Borrows the source component class named \bt_p{name} from the
1077 plugin \bt_p{plugin}.
1078
1079If no source component class has the name \bt_p{name} within
1080\bt_p{plugin}, this function returns \c NULL.
1081
1082@param[in] plugin
1083 Plugin from which to borrow the source component class named
1084 \bt_p{name}.
1085@param[in] name
1086 Name of the source component class to borrow from \bt_p{plugin}.
1087
1088@returns
1089 @parblock
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}.
1093
1094 The returned pointer remains valid as long as \bt_p{plugin} exists.
1095 @endparblock
1096
1097@bt_pre_not_null{plugin}
1098@bt_pre_not_null{name}
1099
1100@sa bt_plugin_borrow_source_component_class_by_index_const() &mdash;
1101 Borrows a source component class by index from a plugin.
1102*/
1103extern const bt_component_class_source *
1104bt_plugin_borrow_source_component_class_by_name_const(
1105 const bt_plugin *plugin, const char *name);
1106
1107/*!
1108@brief
1109 Borrows the filter component class named \bt_p{name} from the
1110 plugin \bt_p{plugin}.
1111
1112If no filter component class has the name \bt_p{name} within
1113\bt_p{plugin}, this function returns \c NULL.
1114
1115@param[in] plugin
1116 Plugin from which to borrow the filter component class named
1117 \bt_p{name}.
1118@param[in] name
1119 Name of the filter component class to borrow from \bt_p{plugin}.
1120
1121@returns
1122 @parblock
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}.
1126
1127 The returned pointer remains valid as long as \bt_p{plugin} exists.
1128 @endparblock
1129
1130@bt_pre_not_null{plugin}
1131@bt_pre_not_null{name}
1132
1133@sa bt_plugin_borrow_filter_component_class_by_index_const() &mdash;
1134 Borrows a filter component class by index from a plugin.
1135*/
1136extern const bt_component_class_filter *
1137bt_plugin_borrow_filter_component_class_by_name_const(
1138 const bt_plugin *plugin, const char *name);
1139
1140/*!
1141@brief
1142 Borrows the sink component class named \bt_p{name} from the
1143 plugin \bt_p{plugin}.
1144
1145If no sink component class has the name \bt_p{name} within
1146\bt_p{plugin}, this function returns \c NULL.
1147
1148@param[in] plugin
1149 Plugin from which to borrow the sink component class named
1150 \bt_p{name}.
1151@param[in] name
1152 Name of the sink component class to borrow from \bt_p{plugin}.
1153
1154@returns
1155 @parblock
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}.
1159
1160 The returned pointer remains valid as long as \bt_p{plugin} exists.
1161 @endparblock
1162
1163@bt_pre_not_null{plugin}
1164@bt_pre_not_null{name}
1165
1166@sa bt_plugin_borrow_sink_component_class_by_index_const() &mdash;
1167 Borrows a sink component class by index from a plugin.
1168*/
1169extern const bt_component_class_sink *
1170bt_plugin_borrow_sink_component_class_by_name_const(
1171 const bt_plugin *plugin, const char *name);
1172
1173/*! @} */
1174
1175/*!
1176@name Plugin reference count
1177@{
1178*/
1179
1180/*!
1181@brief
1182 Increments the \ref api-fund-shared-object "reference count" of
1183 the plugin \bt_p{plugin}.
1184
1185@param[in] plugin
1186 @parblock
1187 Plugin of which to increment the reference count.
1188
1189 Can be \c NULL.
1190 @endparblock
1191
1192@sa bt_plugin_put_ref() &mdash;
1193 Decrements the reference count of a plugin.
1194*/
1195extern void bt_plugin_get_ref(const bt_plugin *plugin);
1196
1197/*!
1198@brief
1199 Decrements the \ref api-fund-shared-object "reference count" of
1200 the plugin \bt_p{plugin}.
1201
1202@param[in] plugin
1203 @parblock
1204 Plugin of which to decrement the reference count.
1205
1206 Can be \c NULL.
1207 @endparblock
1208
1209@sa bt_plugin_get_ref() &mdash;
1210 Increments the reference count of a plugin.
1211*/
1212extern void bt_plugin_put_ref(const bt_plugin *plugin);
1213
1214/*!
1215@brief
1216 Decrements the reference count of the plugin \bt_p{_plugin}, and
1217 then sets \bt_p{_plugin} to \c NULL.
1218
1219@param _plugin
1220 @parblock
1221 Plugin of which to decrement the reference count.
1222
1223 Can contain \c NULL.
1224 @endparblock
1225
1226@bt_pre_assign_expr{_plugin}
1227*/
1228#define BT_PLUGIN_PUT_REF_AND_RESET(_plugin) \
1229 do { \
1230 bt_plugin_put_ref(_plugin); \
1231 (_plugin) = NULL; \
1232 } while (0)
1233
1234/*!
1235@brief
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.
1238
1239This 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.
1242
1243@param _dst
1244 @parblock
1245 Destination expression.
1246
1247 Can contain \c NULL.
1248 @endparblock
1249@param _src
1250 @parblock
1251 Source expression.
1252
1253 Can contain \c NULL.
1254 @endparblock
1255
1256@bt_pre_assign_expr{_dst}
1257@bt_pre_assign_expr{_src}
1258*/
1259#define BT_PLUGIN_MOVE_REF(_dst, _src) \
1260 do { \
1261 bt_plugin_put_ref(_dst); \
1262 (_dst) = (_src); \
1263 (_src) = NULL; \
1264 } while (0)
1265
1266/*! @} */
1267
1268/*!
1269@name Plugin set plugin access
1270@{
1271*/
1272
1273/*!
1274@brief
1275 Returns the number of plugins contained in the
1276 plugin set \bt_p{plugin_set}.
1277
1278@param[in] plugin_set
1279 Plugin set of which to get the number of contained plugins.
1280
1281@returns
1282 Number of contained plugins in \bt_p{plugin_set}.
1283
1284@bt_pre_not_null{plugin}
1285*/
1286extern uint64_t bt_plugin_set_get_plugin_count(
1287 const bt_plugin_set *plugin_set);
1288
1289/*!
1290@brief
1291 Borrows the plugin at index \bt_p{index} from the plugin set
1292 \bt_p{plugin_set}.
1293
1294@param[in] plugin_set
1295 Plugin set from which to borrow the plugin at index \bt_p{index}.
1296@param[in] index
1297 Index of the plugin to borrow from \bt_p{plugin_set}.
1298
1299@returns
1300 @parblock
1301 \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1302 \bt_p{index}.
1303
1304 The returned pointer remains valid until \bt_p{plugin_set} is
1305 modified.
1306 @endparblock
1307
1308@bt_pre_not_null{plugin_set}
1309@pre
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()).
1312*/
1313extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const(
1314 const bt_plugin_set *plugin_set, uint64_t index);
1315
1316/*! @} */
1317
1318/*!
1319@name Plugin set reference count
1320@{
1321*/
1322
1323/*!
1324@brief
1325 Increments the \ref api-fund-shared-object "reference count" of
1326 the plugin set \bt_p{plugin_set}.
1327
1328@param[in] plugin_set
1329 @parblock
1330 Plugin set of which to increment the reference count.
1331
1332 Can be \c NULL.
1333 @endparblock
1334
1335@sa bt_plugin_set_put_ref() &mdash;
1336 Decrements the reference count of a plugin set.
1337*/
1338extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set);
1339
1340/*!
1341@brief
1342 Decrements the \ref api-fund-shared-object "reference count" of
1343 the plugin set \bt_p{plugin_set}.
1344
1345@param[in] plugin_set
1346 @parblock
1347 Plugin set of which to decrement the reference count.
1348
1349 Can be \c NULL.
1350 @endparblock
1351
1352@sa bt_plugin_set_get_ref() &mdash;
1353 Increments the reference count of a plugin set.
1354*/
1355extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set);
1356
1357/*!
1358@brief
1359 Decrements the reference count of the plugin set \bt_p{_plugin_set},
1360 and then sets \bt_p{_plugin_set} to \c NULL.
1361
1362@param _plugin_set
1363 @parblock
1364 Plugin set of which to decrement the reference count.
1365
1366 Can contain \c NULL.
1367 @endparblock
1368
1369@bt_pre_assign_expr{_plugin_set}
1370*/
1371#define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set) \
1372 do { \
1373 bt_plugin_set_put_ref(_plugin_set); \
1374 (_plugin_set) = NULL; \
1375 } while (0)
1376
1377/*!
1378@brief
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.
1381
1382This 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.
1385
1386@param _dst
1387 @parblock
1388 Destination expression.
1389
1390 Can contain \c NULL.
1391 @endparblock
1392@param _src
1393 @parblock
1394 Source expression.
1395
1396 Can contain \c NULL.
1397 @endparblock
1398
1399@bt_pre_assign_expr{_dst}
1400@bt_pre_assign_expr{_src}
1401*/
1402#define BT_PLUGIN_SET_MOVE_REF(_dst, _src) \
1403 do { \
1404 bt_plugin_set_put_ref(_dst); \
1405 (_dst) = (_src); \
1406 (_src) = NULL; \
1407 } while (0)
1408
1409/*! @} */
1410
1411/*! @} */
1412
1413#ifdef __cplusplus
1414}
1415#endif
1416
1417#endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */
This page took 0.089342 seconds and 4 git commands to generate.