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