include/babeltrace2/plugin/plugin-loading.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
   8 #define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  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
  22 extern "C" {
  23 #endif
  24
  25 /*!
  26 @defgroup api-plugin Plugin loading
  27
  28 @brief
  29     Plugin loading functions.
  30
  31 A <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
  40 There 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
  62 libbabeltrace2 loads shared object and Python plugins. Those plugins
  63 need libbabeltrace2 in turn to create and use \bt_name objects:
  64
  65 @image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
  66
  67 A plugin is a \ref api-fund-shared-object "shared object": get a new
  68 reference with bt_plugin_get_ref() and put an existing reference with
  69 bt_plugin_put_ref().
  70
  71 Get the number of \bt_comp_cls in a plugin with
  72 bt_plugin_get_source_component_class_count(),
  73 bt_plugin_get_filter_component_class_count(), and
  74 bt_plugin_get_sink_component_class_count().
  75
  76 Borrow a \bt_comp_cls by index from a plugin with
  77 bt_plugin_borrow_source_component_class_by_index_const(),
  78 bt_plugin_borrow_filter_component_class_by_index_const(), and
  79 bt_plugin_borrow_sink_component_class_by_index_const().
  80
  81 Borrow a \bt_comp_cls by name from a plugin with
  82 bt_plugin_borrow_source_component_class_by_name_const(),
  83 bt_plugin_borrow_filter_component_class_by_name_const(), and
  84 bt_plugin_borrow_sink_component_class_by_name_const().
  85
  86 The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
  87 bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
  88 functions return a <strong>plugin set</strong>, that is, a shared object
  89 containing one or more plugins.
  90
  91 <h1>Find and load plugins</h1>
  92
  93 \anchor api-plugin-def-dirs The bt_plugin_find() and
  94 bt_plugin_find_all() functions find and load plugins from the default
  95 plugin search directories and from the static plugins.
  96
  97 The 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
 115 Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
 116 boolean parameters to include or exclude each of the four locations
 117 above.
 118
 119 <h2>Find and load a plugin by name</h2>
 120
 121 Find and load a plugin by name with bt_plugin_find().
 122
 123 bt_plugin_find() tries to find a plugin with a specific name within
 124 the \ref api-plugin-def-dirs "default plugin search directories"
 125 and static plugins.
 126
 127 <h2>Find and load all the plugins from the default directories</h2>
 128
 129 Load all the plugins found in the
 130 \ref api-plugin-def-dirs "default plugin search directories"
 131 and static plugins with bt_plugin_find_all().
 132
 133 <h2>Find and load plugins from a specific file or directory</h2>
 134
 135 Find and load plugins from a specific file (<code>.so</code>,
 136 <code>.dll</code>, or <code>.py</code>) with
 137 bt_plugin_find_all_from_file().
 138
 139 A single shared object file can contain multiple plugins, although it's
 140 not common practice to do so.
 141
 142 Find and load plugins from a specific directory with
 143 bt_plugin_find_all_from_dir(). This function can search for plugins
 144 within the given directory recursively or not.
 145
 146 <h2>Find and load static plugins</h2>
 147
 148 Find and load static plugins with bt_plugin_find_all_from_static().
 149
 150 A static plugin is built directly into the application or library
 151 instead of being a separate shared object file.
 152
 153 <h1>Plugin properties</h1>
 154
 155 A 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
 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 */
 258 typedef 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
 290 This 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
 319 If this function finds a file which looks like a plugin (shared object
 320 file or Python file with the \c bt_plugin_ prefix), but it fails to load
 321 it for any reason, the function:
 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
 331 If this function doesn't find any plugin, it returns
 332 #BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
 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 */
 377 extern bt_plugin_find_status bt_plugin_find(const char *plugin_name,
 378                 bt_bool find_in_std_env_var, bt_bool find_in_user_dir,
 379                 bt_bool find_in_sys_dir, bt_bool find_in_static,
 380                 bt_bool fail_on_load_error, const bt_plugin **plugin)
 381                 __BT_NOEXCEPT;
 382
 383 /*!
 384 @brief
 385     Status codes for bt_plugin_find_all().
 386 */
 387 typedef enum bt_plugin_find_all_status {
 388         /*!
 389         @brief
 390             Success.
 391         */
 392         BT_PLUGIN_FIND_ALL_STATUS_OK            = __BT_FUNC_STATUS_OK,
 393
 394         /*!
 395         @brief
 396             No plugins found.
 397         */
 398         BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND     = __BT_FUNC_STATUS_NOT_FOUND,
 399
 400         /*!
 401         @brief
 402             Out of memory.
 403         */
 404         BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 405
 406         /*!
 407         @brief
 408             Error.
 409         */
 410         BT_PLUGIN_FIND_ALL_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
 411 } bt_plugin_find_all_status;
 412
 413 /*!
 414 @brief
 415     Finds and loads all the plugins from the default
 416     plugin search directories and static plugins, setting
 417     \bt_p{*plugins} to the result.
 418
 419 This function returns all the plugins within, in order:
 420
 421 -# <strong>If the \bt_p{find_in_std_env_var} parameter is
 422    #BT_TRUE</strong>,
 423    the colon-separated (or semicolon-separated on Windows) list of
 424    directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
 425    if it's set.
 426
 427    The function searches each directory in this list, without recursing.
 428
 429 -# <strong>If the \bt_p{find_in_user_dir} parameter is
 430    #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
 431    without recursing.
 432
 433 -# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
 434    system \bt_name plugin directory, typically
 435    <code>/usr/lib/babeltrace2/plugins</code> or
 436    <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
 437    recursing.
 438
 439 -# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
 440    the static plugins.
 441
 442 During the search process, if a found plugin shares the name of an
 443 already loaded plugin, this function ignores it and continues.
 444
 445 If this function finds a file which looks like a plugin (shared object
 446 file or Python file with the \c bt_plugin_ prefix), but it fails to load
 447 it for any reason, the function:
 448
 449 <dl>
 450   <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
 451   <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
 452
 453   <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
 454   <dd>Ignores the loading error and continues searching.</dd>
 455 </dl>
 456
 457 If this function doesn't find any plugin, it returns
 458 #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
 459 \bt_p{*plugins}.
 460
 461 @param[in] find_in_std_env_var
 462     #BT_TRUE to try to find all the plugins in the
 463     colon-separated (or semicolon-separated on Windows) list of
 464     directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
 465 @param[in] find_in_user_dir
 466     #BT_TRUE to try to find all the plugins in
 467     the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
 468     without recursing.
 469 @param[in] find_in_sys_dir
 470     #BT_TRUE to try to find all the plugins in the system \bt_name
 471     plugin directory.
 472 @param[in] find_in_static
 473     #BT_TRUE to try to find all the plugins in the static plugins.
 474 @param[in] fail_on_load_error
 475     #BT_TRUE to make this function return
 476     #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
 477     of ignoring it.
 478 @param[out] plugins
 479     <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
 480     reference which contains all the plugins found from the default
 481     plugin search directories and static plugins.
 482
 483 @retval #BT_PLUGIN_FIND_ALL_STATUS_OK
 484     Success.
 485 @retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
 486     No plugins found.
 487 @retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
 488     Out of memory.
 489 @retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
 490     Error.
 491
 492 @pre
 493     At least one of the \bt_p{find_in_std_env_var},
 494     \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
 495     \bt_p{find_in_static} parameters is #BT_TRUE.
 496 @bt_pre_not_null{plugins}
 497
 498 @sa bt_plugin_find() &mdash;
 499     Finds and loads a single plugin by name from the default plugin search
 500     directories and static plugins.
 501 */
 502 bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var,
 503                 bt_bool find_in_user_dir, bt_bool find_in_sys_dir,
 504                 bt_bool find_in_static, bt_bool fail_on_load_error,
 505                 const bt_plugin_set **plugins) __BT_NOEXCEPT;
 506
 507 /*!
 508 @brief
 509     Status codes for bt_plugin_find_all_from_file().
 510 */
 511 typedef enum bt_plugin_find_all_from_file_status {
 512         /*!
 513         @brief
 514             Success.
 515         */
 516         BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 517
 518         /*!
 519         @brief
 520             No plugins found.
 521         */
 522         BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND           = __BT_FUNC_STATUS_NOT_FOUND,
 523
 524         /*!
 525         @brief
 526             Out of memory.
 527         */
 528         BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
 529
 530         /*!
 531         @brief
 532             Error.
 533         */
 534         BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
 535 } bt_plugin_find_all_from_file_status;
 536
 537 /*!
 538 @brief
 539     Finds and loads all the plugins from the file with path \bt_p{path},
 540     setting \bt_p{*plugins} to the result.
 541
 542 @note
 543     A plugin's name is not related to the name of its file (shared
 544     object or Python file). For example, a plugin found in the file
 545     \c patente.so can be named <code>Dan</code>.
 546
 547 If any plugin loading error occurs during this function's execution, the
 548 function:
 549
 550 <dl>
 551   <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
 552   <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
 553
 554   <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
 555   <dd>Ignores the loading error and continues.</dd>
 556 </dl>
 557
 558 If this function doesn't find any plugin, it returns
 559 #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
 560 \bt_p{*plugins}.
 561
 562 @param[in] path
 563     Path of the file in which to find and load all the plugins.
 564 @param[in] fail_on_load_error
 565     #BT_TRUE to make this function return
 566     #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
 567     error instead of ignoring it.
 568 @param[out] plugins
 569     <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
 570     reference which contains all the plugins found in the file with path
 571     \bt_p{path}.
 572
 573 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
 574     Success.
 575 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
 576     No plugins found.
 577 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
 578     Out of memory.
 579 @retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
 580     Error.
 581
 582 @bt_pre_not_null{path}
 583 @pre
 584     \bt_p{path} is the path of a regular file.
 585 @bt_pre_not_null{plugins}
 586
 587 @sa bt_plugin_find_all_from_dir() &mdash;
 588     Finds and loads all plugins from a given directory.
 589 */
 590 extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file(
 591                 const char *path, bt_bool fail_on_load_error,
 592                 const bt_plugin_set **plugins) __BT_NOEXCEPT;
 593
 594 /*!
 595 @brief
 596     Status codes for bt_plugin_find_all_from_dir().
 597 */
 598 typedef enum bt_plugin_find_all_from_dir_status {
 599         /*!
 600         @brief
 601             Success.
 602         */
 603         BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK                   = __BT_FUNC_STATUS_OK,
 604
 605         /*!
 606         @brief
 607             No plugins found.
 608         */
 609         BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND            = __BT_FUNC_STATUS_NOT_FOUND,
 610
 611         /*!
 612         @brief
 613             Out of memory.
 614         */
 615         BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR         = __BT_FUNC_STATUS_MEMORY_ERROR,
 616
 617         /*!
 618         @brief
 619             Error.
 620         */
 621         BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR                = __BT_FUNC_STATUS_ERROR,
 622 } bt_plugin_find_all_from_dir_status;
 623
 624 /*!
 625 @brief
 626     Finds and loads all the plugins from the directory with path
 627     \bt_p{path}, setting \bt_p{*plugins} to the result.
 628
 629 If \bt_p{recurse} is #BT_TRUE, this function recurses into the
 630 subdirectories of \bt_p{path} to find plugins.
 631
 632 During the search process, if a found plugin shares the name of an
 633 already loaded plugin, this function ignores it and continues.
 634
 635 @attention
 636     As of \bt_name_version_min_maj, the file and directory traversal
 637     order is undefined.
 638
 639 If any plugin loading error occurs during this function's execution, the
 640 function:
 641
 642 <dl>
 643   <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
 644   <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
 645
 646   <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
 647   <dd>Ignores the loading error and continues.</dd>
 648 </dl>
 649
 650 If this function doesn't find any plugin, it returns
 651 #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
 652 \bt_p{*plugins}.
 653
 654 @param[in] path
 655     Path of the directory in which to find and load all the plugins.
 656 @param[in] recurse
 657     #BT_TRUE to make this function recurse into the subdirectories
 658     of \bt_p{path}.
 659 @param[in] fail_on_load_error
 660     #BT_TRUE to make this function return
 661     #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
 662     error instead of ignoring it.
 663 @param[out] plugins
 664     <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
 665     reference which contains all the plugins found in the directory with
 666     path \bt_p{path}.
 667
 668 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
 669     Success.
 670 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
 671     No plugins found.
 672 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
 673     Out of memory.
 674 @retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
 675     Error.
 676
 677 @bt_pre_not_null{path}
 678 @pre
 679     \bt_p{path} is the path of a directory.
 680 @bt_pre_not_null{plugins}
 681
 682 @sa bt_plugin_find_all_from_file() &mdash;
 683     Finds and loads all plugins from a given file.
 684 */
 685 extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir(
 686                 const char *path, bt_bool recurse, bt_bool fail_on_load_error,
 687                 const bt_plugin_set **plugins) __BT_NOEXCEPT;
 688
 689 /*!
 690 @brief
 691     Status codes for bt_plugin_find_all_from_static().
 692 */
 693 typedef enum bt_plugin_find_all_from_static_status {
 694         /*!
 695         @brief
 696             Success.
 697         */
 698         BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK                        = __BT_FUNC_STATUS_OK,
 699
 700         /*!
 701         @brief
 702             No static plugins found.
 703         */
 704         BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND                 = __BT_FUNC_STATUS_NOT_FOUND,
 705
 706         /*!
 707         @brief
 708             Out of memory.
 709         */
 710         BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR              = __BT_FUNC_STATUS_MEMORY_ERROR,
 711
 712         /*!
 713         @brief
 714             Error.
 715         */
 716         BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR                     = __BT_FUNC_STATUS_ERROR,
 717 } bt_plugin_find_all_from_static_status;
 718
 719 /*!
 720 @brief
 721     Finds and loads all the static plugins,
 722     setting \bt_p{*plugins} to the result.
 723
 724 A static plugin is built directly into the application or library
 725 instead of being a separate shared object file.
 726
 727 If any plugin loading error occurs during this function's execution, the
 728 function:
 729
 730 <dl>
 731   <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
 732   <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
 733
 734   <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
 735   <dd>Ignores the loading error and continues.</dd>
 736 </dl>
 737
 738 If this function doesn't find any plugin, it returns
 739 #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
 740 \bt_p{*plugins}.
 741
 742 @param[in] fail_on_load_error
 743     #BT_TRUE to make this function return
 744     #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
 745     error instead of ignoring it.
 746 @param[out] plugins
 747     <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
 748     reference which contains all the static plugins.
 749
 750 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
 751     Success.
 752 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
 753     No static plugins found.
 754 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
 755     Out of memory.
 756 @retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
 757     Error.
 758
 759 @bt_pre_not_null{path}
 760 @bt_pre_not_null{plugins}
 761 */
 762 extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static(
 763                 bt_bool fail_on_load_error, const bt_plugin_set **plugins)
 764                 __BT_NOEXCEPT;
 765
 766 /*! @} */
 767
 768 /*!
 769 @name Plugin properties
 770 @{
 771 */
 772
 773 /*!
 774 @brief
 775     Returns the name of the plugin \bt_p{plugin}.
 776
 777 See the \ref api-plugin-prop-name "name" property.
 778
 779 @param[in] plugin
 780     Plugin of which to get the name.
 781
 782 @returns
 783     @parblock
 784     Name of \bt_p{plugin}.
 785
 786     The returned pointer remains valid as long as \bt_p{plugin} exists.
 787     @endparblock
 788
 789 @bt_pre_not_null{plugin}
 790 */
 791 extern const char *bt_plugin_get_name(const bt_plugin *plugin) __BT_NOEXCEPT;
 792
 793 /*!
 794 @brief
 795     Returns the description of the plugin \bt_p{plugin}.
 796
 797 See the \ref api-plugin-prop-descr "description" property.
 798
 799 @param[in] plugin
 800     Plugin of which to get description.
 801
 802 @returns
 803     @parblock
 804     Description of \bt_p{plugin}, or \c NULL if not available.
 805
 806     The returned pointer remains valid as long as \bt_p{plugin} exists.
 807     @endparblock
 808
 809 @bt_pre_not_null{plugin}
 810 */
 811 extern const char *bt_plugin_get_description(const bt_plugin *plugin)
 812                 __BT_NOEXCEPT;
 813
 814 /*!
 815 @brief
 816     Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
 817
 818 See the \ref api-plugin-prop-author "author name(s)" property.
 819
 820 @param[in] plugin
 821     Plugin of which to get the author name(s).
 822
 823 @returns
 824     @parblock
 825     Author name(s) of \bt_p{plugin}, or \c NULL if not available.
 826
 827     The returned pointer remains valid as long as \bt_p{plugin} exists.
 828     @endparblock
 829
 830 @bt_pre_not_null{plugin}
 831 */
 832 extern const char *bt_plugin_get_author(const bt_plugin *plugin) __BT_NOEXCEPT;
 833
 834 /*!
 835 @brief
 836     Returns the license text or the license name of the plugin
 837     \bt_p{plugin}.
 838
 839 See the \ref api-plugin-prop-license "license" property.
 840
 841 @param[in] plugin
 842     Plugin of which to get the license.
 843
 844 @returns
 845     @parblock
 846     License of \bt_p{plugin}, or \c NULL if not available.
 847
 848     The returned pointer remains valid as long as \bt_p{plugin} exists.
 849     @endparblock
 850
 851 @bt_pre_not_null{plugin}
 852 */
 853 extern const char *bt_plugin_get_license(const bt_plugin *plugin) __BT_NOEXCEPT;
 854
 855 /*!
 856 @brief
 857     Returns the path of the file which contains the plugin
 858     \bt_p{plugin}.
 859
 860 See the \ref api-plugin-prop-path "path" property.
 861
 862 This function returns \c NULL if \bt_p{plugin} is a static plugin
 863 because a static plugin has no path property.
 864
 865 @param[in] plugin
 866     Plugin of which to get the containing file's path.
 867
 868 @returns
 869     @parblock
 870     Path of the file which contains \bt_p{plugin}, or \c NULL if
 871     not available.
 872
 873     The returned pointer remains valid as long as \bt_p{plugin} exists.
 874     @endparblock
 875
 876 @bt_pre_not_null{plugin}
 877 */
 878 extern const char *bt_plugin_get_path(const bt_plugin *plugin) __BT_NOEXCEPT;
 879
 880 /*!
 881 @brief
 882     Returns the version of the plugin \bt_p{plugin}.
 883
 884 See the \ref api-plugin-prop-version "version" property.
 885
 886 @param[in] plugin
 887     Plugin of which to get the version.
 888 @param[out] major
 889     <strong>If not \c NULL and this function returns
 890     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
 891     major version of \bt_p{plugin}.
 892 @param[out] minor
 893     <strong>If not \c NULL and this function returns
 894     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
 895     minor version of \bt_p{plugin}.
 896 @param[out] patch
 897     <strong>If not \c NULL and this function returns
 898     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
 899     patch version of \bt_p{plugin}.
 900 @param[out] extra
 901     @parblock
 902     <strong>If not \c NULL and this function returns
 903     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
 904     version's extra information of \bt_p{plugin}.
 905
 906     \bt_p{*extra} can be \c NULL if the plugin's version has no extra
 907     information.
 908
 909     \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
 910     @endparblock
 911
 912 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
 913     The version of \bt_p{plugin} is available.
 914 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
 915     The version of \bt_p{plugin} is not available.
 916
 917 @bt_pre_not_null{plugin}
 918 */
 919 extern bt_property_availability bt_plugin_get_version(
 920                 const bt_plugin *plugin, unsigned int *major,
 921                 unsigned int *minor, unsigned int *patch, const char **extra)
 922                 __BT_NOEXCEPT;
 923
 924 /*! @} */
 925
 926 /*!
 927 @name Plugin component class access
 928 @{
 929 */
 930
 931 /*!
 932 @brief
 933     Returns the number of source component classes contained in the
 934     plugin \bt_p{plugin}.
 935
 936 @param[in] plugin
 937     Plugin of which to get the number of contained source
 938     component classes.
 939
 940 @returns
 941     Number of contained source component classes in \bt_p{plugin}.
 942
 943 @bt_pre_not_null{plugin}
 944 */
 945 extern uint64_t bt_plugin_get_source_component_class_count(
 946                 const bt_plugin *plugin) __BT_NOEXCEPT;
 947
 948 /*!
 949 @brief
 950     Returns the number of filter component classes contained in the
 951     plugin \bt_p{plugin}.
 952
 953 @param[in] plugin
 954     Plugin of which to get the number of contained filter
 955     component classes.
 956
 957 @returns
 958     Number of contained filter component classes in \bt_p{plugin}.
 959
 960 @bt_pre_not_null{plugin}
 961 */
 962 extern uint64_t bt_plugin_get_filter_component_class_count(
 963                 const bt_plugin *plugin) __BT_NOEXCEPT;
 964
 965 /*!
 966 @brief
 967     Returns the number of sink component classes contained in the
 968     plugin \bt_p{plugin}.
 969
 970 @param[in] plugin
 971     Plugin of which to get the number of contained sink
 972     component classes.
 973
 974 @returns
 975     Number of contained sink component classes in \bt_p{plugin}.
 976
 977 @bt_pre_not_null{plugin}
 978 */
 979 extern uint64_t bt_plugin_get_sink_component_class_count(
 980                 const bt_plugin *plugin) __BT_NOEXCEPT;
 981
 982 /*!
 983 @brief
 984     Borrows the source component class at index \bt_p{index} from the
 985     plugin \bt_p{plugin}.
 986
 987 @param[in] plugin
 988     Plugin from which to borrow the source component class at index
 989     \bt_p{index}.
 990 @param[in] index
 991     Index of the source component class to borrow from \bt_p{plugin}.
 992
 993 @returns
 994     @parblock
 995     \em Borrowed reference of the source component class of
 996     \bt_p{plugin} at index \bt_p{index}.
 997
 998     The returned pointer remains valid as long as \bt_p{plugin} exists.
 999     @endparblock
1000
1001 @bt_pre_not_null{plugin}
1002 @pre
1003     \bt_p{index} is less than the number of source component classes in
1004     \bt_p{plugin} (as returned by
1005     bt_plugin_get_source_component_class_count()).
1006
1007 @sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1008     Borrows a source component class by name from a plugin.
1009 */
1010 extern const bt_component_class_source *
1011 bt_plugin_borrow_source_component_class_by_index_const(
1012                 const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT;
1013
1014 /*!
1015 @brief
1016     Borrows the filter component class at index \bt_p{index} from the
1017     plugin \bt_p{plugin}.
1018
1019 @param[in] plugin
1020     Plugin from which to borrow the filter component class at index
1021     \bt_p{index}.
1022 @param[in] index
1023     Index of the filter component class to borrow from \bt_p{plugin}.
1024
1025 @returns
1026     @parblock
1027     \em Borrowed reference of the filter component class of
1028     \bt_p{plugin} at index \bt_p{index}.
1029
1030     The returned pointer remains valid as long as \bt_p{plugin} exists.
1031     @endparblock
1032
1033 @bt_pre_not_null{plugin}
1034 @pre
1035     \bt_p{index} is less than the number of filter component classes in
1036     \bt_p{plugin} (as returned by
1037     bt_plugin_get_source_component_class_count()).
1038
1039 @sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1040     Borrows a filter component class by name from a plugin.
1041 */
1042 extern const bt_component_class_filter *
1043 bt_plugin_borrow_filter_component_class_by_index_const(
1044                 const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT;
1045
1046 /*!
1047 @brief
1048     Borrows the sink component class at index \bt_p{index} from the
1049     plugin \bt_p{plugin}.
1050
1051 @param[in] plugin
1052     Plugin from which to borrow the sink component class at index
1053     \bt_p{index}.
1054 @param[in] index
1055     Index of the sink component class to borrow from \bt_p{plugin}.
1056
1057 @returns
1058     @parblock
1059     \em Borrowed reference of the sink component class of
1060     \bt_p{plugin} at index \bt_p{index}.
1061
1062     The returned pointer remains valid as long as \bt_p{plugin} exists.
1063     @endparblock
1064
1065 @bt_pre_not_null{plugin}
1066 @pre
1067     \bt_p{index} is less than the number of sink component classes in
1068     \bt_p{plugin} (as returned by
1069     bt_plugin_get_source_component_class_count()).
1070
1071 @sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
1072     Borrows a sink component class by name from a plugin.
1073 */
1074 extern const bt_component_class_sink *
1075 bt_plugin_borrow_sink_component_class_by_index_const(
1076                 const bt_plugin *plugin, uint64_t index) __BT_NOEXCEPT;
1077
1078 /*!
1079 @brief
1080     Borrows the source component class named \bt_p{name} from the
1081     plugin \bt_p{plugin}.
1082
1083 If no source component class has the name \bt_p{name} within
1084 \bt_p{plugin}, this function returns \c NULL.
1085
1086 @param[in] plugin
1087     Plugin from which to borrow the source component class named
1088     \bt_p{name}.
1089 @param[in] name
1090     Name of the source component class to borrow from \bt_p{plugin}.
1091
1092 @returns
1093     @parblock
1094     \em Borrowed reference of the source component class of
1095     \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
1096     class is named \bt_p{name} within \bt_p{plugin}.
1097
1098     The returned pointer remains valid as long as \bt_p{plugin} exists.
1099     @endparblock
1100
1101 @bt_pre_not_null{plugin}
1102 @bt_pre_not_null{name}
1103
1104 @sa bt_plugin_borrow_source_component_class_by_index_const() &mdash;
1105     Borrows a source component class by index from a plugin.
1106 */
1107 extern const bt_component_class_source *
1108 bt_plugin_borrow_source_component_class_by_name_const(
1109                 const bt_plugin *plugin, const char *name) __BT_NOEXCEPT;
1110
1111 /*!
1112 @brief
1113     Borrows the filter component class named \bt_p{name} from the
1114     plugin \bt_p{plugin}.
1115
1116 If no filter component class has the name \bt_p{name} within
1117 \bt_p{plugin}, this function returns \c NULL.
1118
1119 @param[in] plugin
1120     Plugin from which to borrow the filter component class named
1121     \bt_p{name}.
1122 @param[in] name
1123     Name of the filter component class to borrow from \bt_p{plugin}.
1124
1125 @returns
1126     @parblock
1127     \em Borrowed reference of the filter component class of
1128     \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
1129     class is named \bt_p{name} within \bt_p{plugin}.
1130
1131     The returned pointer remains valid as long as \bt_p{plugin} exists.
1132     @endparblock
1133
1134 @bt_pre_not_null{plugin}
1135 @bt_pre_not_null{name}
1136
1137 @sa bt_plugin_borrow_filter_component_class_by_index_const() &mdash;
1138     Borrows a filter component class by index from a plugin.
1139 */
1140 extern const bt_component_class_filter *
1141 bt_plugin_borrow_filter_component_class_by_name_const(
1142                 const bt_plugin *plugin, const char *name) __BT_NOEXCEPT;
1143
1144 /*!
1145 @brief
1146     Borrows the sink component class named \bt_p{name} from the
1147     plugin \bt_p{plugin}.
1148
1149 If no sink component class has the name \bt_p{name} within
1150 \bt_p{plugin}, this function returns \c NULL.
1151
1152 @param[in] plugin
1153     Plugin from which to borrow the sink component class named
1154     \bt_p{name}.
1155 @param[in] name
1156     Name of the sink component class to borrow from \bt_p{plugin}.
1157
1158 @returns
1159     @parblock
1160     \em Borrowed reference of the sink component class of
1161     \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
1162     class is named \bt_p{name} within \bt_p{plugin}.
1163
1164     The returned pointer remains valid as long as \bt_p{plugin} exists.
1165     @endparblock
1166
1167 @bt_pre_not_null{plugin}
1168 @bt_pre_not_null{name}
1169
1170 @sa bt_plugin_borrow_sink_component_class_by_index_const() &mdash;
1171     Borrows a sink component class by index from a plugin.
1172 */
1173 extern const bt_component_class_sink *
1174 bt_plugin_borrow_sink_component_class_by_name_const(
1175                 const bt_plugin *plugin, const char *name) __BT_NOEXCEPT;
1176
1177 /*! @} */
1178
1179 /*!
1180 @name Plugin reference count
1181 @{
1182 */
1183
1184 /*!
1185 @brief
1186     Increments the \ref api-fund-shared-object "reference count" of
1187     the plugin \bt_p{plugin}.
1188
1189 @param[in] plugin
1190     @parblock
1191     Plugin of which to increment the reference count.
1192
1193     Can be \c NULL.
1194     @endparblock
1195
1196 @sa bt_plugin_put_ref() &mdash;
1197     Decrements the reference count of a plugin.
1198 */
1199 extern void bt_plugin_get_ref(const bt_plugin *plugin) __BT_NOEXCEPT;
1200
1201 /*!
1202 @brief
1203     Decrements the \ref api-fund-shared-object "reference count" of
1204     the plugin \bt_p{plugin}.
1205
1206 @param[in] plugin
1207     @parblock
1208     Plugin of which to decrement the reference count.
1209
1210     Can be \c NULL.
1211     @endparblock
1212
1213 @sa bt_plugin_get_ref() &mdash;
1214     Increments the reference count of a plugin.
1215 */
1216 extern void bt_plugin_put_ref(const bt_plugin *plugin) __BT_NOEXCEPT;
1217
1218 /*!
1219 @brief
1220     Decrements the reference count of the plugin \bt_p{_plugin}, and
1221     then sets \bt_p{_plugin} to \c NULL.
1222
1223 @param _plugin
1224     @parblock
1225     Plugin of which to decrement the reference count.
1226
1227     Can contain \c NULL.
1228     @endparblock
1229
1230 @bt_pre_assign_expr{_plugin}
1231 */
1232 #define BT_PLUGIN_PUT_REF_AND_RESET(_plugin)            \
1233         do {                                            \
1234                 bt_plugin_put_ref(_plugin);             \
1235                 (_plugin) = NULL;                       \
1236         } while (0)
1237
1238 /*!
1239 @brief
1240     Decrements the reference count of the plugin \bt_p{_dst}, sets
1241     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1242
1243 This macro effectively moves a plugin reference from the expression
1244 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1245 \bt_p{_dst} reference.
1246
1247 @param _dst
1248     @parblock
1249     Destination expression.
1250
1251     Can contain \c NULL.
1252     @endparblock
1253 @param _src
1254     @parblock
1255     Source expression.
1256
1257     Can contain \c NULL.
1258     @endparblock
1259
1260 @bt_pre_assign_expr{_dst}
1261 @bt_pre_assign_expr{_src}
1262 */
1263 #define BT_PLUGIN_MOVE_REF(_dst, _src)          \
1264         do {                                    \
1265                 bt_plugin_put_ref(_dst);        \
1266                 (_dst) = (_src);                \
1267                 (_src) = NULL;                  \
1268         } while (0)
1269
1270 /*! @} */
1271
1272 /*!
1273 @name Plugin set plugin access
1274 @{
1275 */
1276
1277 /*!
1278 @brief
1279     Returns the number of plugins contained in the
1280     plugin set \bt_p{plugin_set}.
1281
1282 @param[in] plugin_set
1283     Plugin set of which to get the number of contained plugins.
1284
1285 @returns
1286     Number of contained plugins in \bt_p{plugin_set}.
1287
1288 @bt_pre_not_null{plugin}
1289 */
1290 extern uint64_t bt_plugin_set_get_plugin_count(
1291                 const bt_plugin_set *plugin_set) __BT_NOEXCEPT;
1292
1293 /*!
1294 @brief
1295     Borrows the plugin at index \bt_p{index} from the plugin set
1296     \bt_p{plugin_set}.
1297
1298 @param[in] plugin_set
1299     Plugin set from which to borrow the plugin at index \bt_p{index}.
1300 @param[in] index
1301     Index of the plugin to borrow from \bt_p{plugin_set}.
1302
1303 @returns
1304     @parblock
1305     \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
1306     \bt_p{index}.
1307
1308     The returned pointer remains valid until \bt_p{plugin_set} is
1309     modified.
1310     @endparblock
1311
1312 @bt_pre_not_null{plugin_set}
1313 @pre
1314     \bt_p{index} is less than the number of plugins in
1315     \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
1316 */
1317 extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const(
1318                 const bt_plugin_set *plugin_set, uint64_t index) __BT_NOEXCEPT;
1319
1320 /*! @} */
1321
1322 /*!
1323 @name Plugin set reference count
1324 @{
1325 */
1326
1327 /*!
1328 @brief
1329     Increments the \ref api-fund-shared-object "reference count" of
1330     the plugin set \bt_p{plugin_set}.
1331
1332 @param[in] plugin_set
1333     @parblock
1334     Plugin set of which to increment the reference count.
1335
1336     Can be \c NULL.
1337     @endparblock
1338
1339 @sa bt_plugin_set_put_ref() &mdash;
1340     Decrements the reference count of a plugin set.
1341 */
1342 extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set)
1343                 __BT_NOEXCEPT;
1344
1345 /*!
1346 @brief
1347     Decrements the \ref api-fund-shared-object "reference count" of
1348     the plugin set \bt_p{plugin_set}.
1349
1350 @param[in] plugin_set
1351     @parblock
1352     Plugin set of which to decrement the reference count.
1353
1354     Can be \c NULL.
1355     @endparblock
1356
1357 @sa bt_plugin_set_get_ref() &mdash;
1358     Increments the reference count of a plugin set.
1359 */
1360 extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set)
1361                 __BT_NOEXCEPT;
1362
1363 /*!
1364 @brief
1365     Decrements the reference count of the plugin set \bt_p{_plugin_set},
1366     and then sets \bt_p{_plugin_set} to \c NULL.
1367
1368 @param _plugin_set
1369     @parblock
1370     Plugin set of which to decrement the reference count.
1371
1372     Can contain \c NULL.
1373     @endparblock
1374
1375 @bt_pre_assign_expr{_plugin_set}
1376 */
1377 #define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set)    \
1378         do {                                            \
1379                 bt_plugin_set_put_ref(_plugin_set);     \
1380                 (_plugin_set) = NULL;                   \
1381         } while (0)
1382
1383 /*!
1384 @brief
1385     Decrements the reference count of the plugin set \bt_p{_dst}, sets
1386     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1387
1388 This macro effectively moves a plugin set reference from the expression
1389 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1390 \bt_p{_dst} reference.
1391
1392 @param _dst
1393     @parblock
1394     Destination expression.
1395
1396     Can contain \c NULL.
1397     @endparblock
1398 @param _src
1399     @parblock
1400     Source expression.
1401
1402     Can contain \c NULL.
1403     @endparblock
1404
1405 @bt_pre_assign_expr{_dst}
1406 @bt_pre_assign_expr{_src}
1407 */
1408 #define BT_PLUGIN_SET_MOVE_REF(_dst, _src)      \
1409         do {                                    \
1410                 bt_plugin_set_put_ref(_dst);    \
1411                 (_dst) = (_src);                \
1412                 (_src) = NULL;                  \
1413         } while (0)
1414
1415 /*! @} */
1416
1417 /*! @} */
1418
1419 #ifdef __cplusplus
1420 }
1421 #endif
1422
1423 #endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */