include/babeltrace2/plugin/plugin-loading.h

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