include/babeltrace2/graph/component-class.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H
   8 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-comp-cls Component classes
  24 @ingroup api-graph
  25
  26 @brief
  27     Source, filter, and sink component classes (non-development).
  28
  29 A <strong><em>component class</em></strong> is the class of a \bt_comp:
  30
  31 @image html component.png
  32
  33 @attention
  34     This module (component class API) offers basic, read-only functions
  35     to get component class properties. To \em create a component class,
  36     see \ref api-comp-cls-dev or \ref api-plugin-dev.
  37
  38 You can instantiate a given component class many times, with different
  39 initialization parameters, to create many components with the
  40 <code>bt_graph_add_*_component*()</code> functions (see \ref api-graph).
  41
  42 There are two ways to obtain a component class:
  43
  44 - Create one programmatically: see \ref api-comp-cls-dev.
  45
  46 - Borrow one from a \bt_plugin.
  47
  48   Note that, as of \bt_name_version_min_maj, you cannot access a
  49   component class's plugin, if any.
  50
  51 A component class is a \ref api-fund-shared-object "shared object": get
  52 a new reference with bt_component_class_get_ref() and put an existing
  53 reference with bt_component_class_put_ref().
  54
  55 The common C&nbsp;type of a component class is #bt_component_class.
  56
  57 There are three types of component classes:
  58
  59 <dl>
  60   <dt>\anchor api-comp-cls-src Source component class</dt>
  61   <dd>
  62     A source component class instance (a \bt_src_comp) \bt_msg_iter
  63     emits fresh \bt_p_msg.
  64
  65     A source component class's specific type is
  66     #bt_component_class_source and its type enumerator is
  67     #BT_COMPONENT_CLASS_TYPE_SOURCE.
  68
  69     \ref api-fund-c-typing "Upcast" the #bt_component_class_source type
  70     to the #bt_component_class type with
  71     bt_component_class_source_as_component_class_const().
  72
  73     Get a new source component class reference with Use
  74     bt_component_class_source_get_ref() and put an existing one with
  75     bt_component_class_source_put_ref().
  76   </dd>
  77
  78   <dt>\anchor api-comp-cls-flt Filter component class</dt>
  79   <dd>
  80     A filter component class instance (a \bt_flt_comp) message iterator
  81     emits fresh and transformed messages. It can also discard
  82     existing messages.
  83
  84     A filter component class's specific type is
  85     #bt_component_class_filter and its type enumerator is
  86     #BT_COMPONENT_CLASS_TYPE_FILTER.
  87
  88     \ref api-fund-c-typing "Upcast" the #bt_component_class_filter type
  89     to the #bt_component_class type with
  90     bt_component_class_filter_as_component_class_const().
  91
  92     Get a new filter component class reference with
  93     bt_component_class_filter_get_ref() and put an existing one with
  94     bt_component_class_filter_put_ref().
  95   </dd>
  96
  97   <dt>\anchor api-comp-cls-sink Sink component class</dt>
  98   <dd>
  99     A sink component class instance (a \bt_sink_comp) consumes messages
 100     from a source or filter message iterator.
 101
 102     A filter component class's specific type is #bt_component_class_sink
 103     and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
 104
 105     \ref api-fund-c-typing "Upcast" the #bt_component_class_sink type to
 106     the #bt_component_class type with
 107     bt_component_class_sink_as_component_class_const().
 108
 109     Get a new sink component class reference with
 110     bt_component_class_sink_get_ref() and put an existing one with
 111     bt_component_class_sink_put_ref().
 112   </dd>
 113 </dl>
 114
 115 Get a component's class type enumerator with
 116 bt_component_class_get_type(). You can also use the
 117 bt_component_class_is_source(), bt_component_class_is_filter(), and
 118 bt_component_class_is_sink() helper functions.
 119
 120 <h1>Properties</h1>
 121
 122 A component class has the following common properties:
 123
 124 <dl>
 125   <dt>
 126     \anchor api-comp-cls-prop-name
 127     Name
 128   </dt>
 129   <dd>
 130     Name of the component class.
 131
 132     Within a \bt_plugin, for a given component class type, each
 133     component class has a unique name.
 134
 135     Get a component class's name with bt_component_class_get_name().
 136   </dd>
 137
 138   <dt>
 139     \anchor api-comp-cls-prop-descr
 140     \bt_dt_opt Description
 141   </dt>
 142   <dd>
 143     Textual description of the component class.
 144
 145     Get a component class's description with
 146     bt_component_class_get_description().
 147   </dd>
 148
 149   <dt>
 150     \anchor api-comp-cls-prop-help
 151     \bt_dt_opt Help text
 152   </dt>
 153   <dd>
 154     Help text of the component class.
 155
 156     Get a component class's help text with
 157     bt_component_class_get_help().
 158   </dd>
 159 </dl>
 160 */
 161
 162 /*! @{ */
 163
 164 /*!
 165 @name Types
 166 @{
 167
 168 @typedef struct bt_component_class bt_component_class;
 169
 170 @brief
 171     Component class.
 172
 173 @typedef struct bt_component_class_source bt_component_class_source;
 174
 175 @brief
 176     \bt_c_src_comp_cls.
 177
 178 @typedef struct bt_component_class_filter bt_component_class_filter;
 179
 180 @brief
 181     \bt_c_flt_comp_cls.
 182
 183 @typedef struct bt_component_class_sink bt_component_class_sink;
 184
 185 @brief
 186     \bt_c_sink_comp_cls.
 187
 188 @}
 189 */
 190
 191 /*!
 192 @name Type query
 193 @{
 194 */
 195
 196 /*!
 197 @brief
 198     Component class type enumerators.
 199 */
 200 typedef enum bt_component_class_type {
 201         /*!
 202         @brief
 203             \bt_c_src_comp_cls.
 204         */
 205         BT_COMPONENT_CLASS_TYPE_SOURCE  = 1 << 0,
 206
 207         /*!
 208         @brief
 209             \bt_c_flt_comp_cls.
 210         */
 211         BT_COMPONENT_CLASS_TYPE_FILTER  = 1 << 1,
 212
 213         /*!
 214         @brief
 215             \bt_c_sink_comp_cls.
 216         */
 217         BT_COMPONENT_CLASS_TYPE_SINK    = 1 << 2,
 218 } bt_component_class_type;
 219
 220 /*!
 221 @brief
 222     Returns the type enumerator of the component class
 223     \bt_p{component_class}.
 224
 225 @param[in] component_class
 226     Component class of which to get the type enumerator.
 227
 228 @returns
 229     Type enumerator of \bt_p{component_class}.
 230
 231 @bt_pre_not_null{component_class}
 232
 233 @sa bt_component_class_is_source() &mdash;
 234     Returns whether or not a component class is a \bt_src_comp_cls.
 235 @sa bt_component_class_is_filter() &mdash;
 236     Returns whether or not a component class is a \bt_flt_comp_cls.
 237 @sa bt_component_class_is_sink() &mdash;
 238     Returns whether or not a component class is a \bt_sink_comp_cls.
 239 */
 240 extern bt_component_class_type bt_component_class_get_type(
 241                 const bt_component_class *component_class) __BT_NOEXCEPT;
 242
 243 /*!
 244 @brief
 245     Returns whether or not the component class \bt_p{component_class}
 246     is a \bt_src_comp_cls.
 247
 248 @param[in] component_class
 249     Component class to check.
 250
 251 @returns
 252     #BT_TRUE if \bt_p{component_class} is a source component class.
 253
 254 @bt_pre_not_null{component_class}
 255
 256 @sa bt_component_class_get_type() &mdash;
 257     Returns the type enumerator of a component class.
 258 */
 259 static inline
 260 bt_bool bt_component_class_is_source(
 261                 const bt_component_class *component_class) __BT_NOEXCEPT
 262 {
 263         return bt_component_class_get_type(component_class) ==
 264                 BT_COMPONENT_CLASS_TYPE_SOURCE;
 265 }
 266
 267 /*!
 268 @brief
 269     Returns whether or not the component class \bt_p{component_class}
 270     is a \bt_flt_comp_cls.
 271
 272 @param[in] component_class
 273     Component class to check.
 274
 275 @returns
 276     #BT_TRUE if \bt_p{component_class} is a filter component class.
 277
 278 @bt_pre_not_null{component_class}
 279
 280 @sa bt_component_class_get_type() &mdash;
 281     Returns the type enumerator of a component class.
 282 */
 283 static inline
 284 bt_bool bt_component_class_is_filter(
 285                 const bt_component_class *component_class) __BT_NOEXCEPT
 286 {
 287         return bt_component_class_get_type(component_class) ==
 288                 BT_COMPONENT_CLASS_TYPE_FILTER;
 289 }
 290
 291 /*!
 292 @brief
 293     Returns whether or not the component class \bt_p{component_class}
 294     is a \bt_sink_comp_cls.
 295
 296 @param[in] component_class
 297     Component class to check.
 298
 299 @returns
 300     #BT_TRUE if \bt_p{component_class} is a sink component class.
 301
 302 @bt_pre_not_null{component_class}
 303
 304 @sa bt_component_class_get_type() &mdash;
 305     Returns the type enumerator of a component class.
 306 */
 307 static inline
 308 bt_bool bt_component_class_is_sink(
 309                 const bt_component_class *component_class) __BT_NOEXCEPT
 310 {
 311         return bt_component_class_get_type(component_class) ==
 312                 BT_COMPONENT_CLASS_TYPE_SINK;
 313 }
 314
 315 /*! @} */
 316
 317 /*!
 318 @name Properties
 319 @{
 320 */
 321
 322 /*!
 323 @brief
 324     Returns the name of the component class \bt_p{component_class}.
 325
 326 See the \ref api-comp-cls-prop-name "name" property.
 327
 328 @param[in] component_class
 329     Component class of which to get the name.
 330
 331 @returns
 332     @parblock
 333     Name of \bt_p{component_class}.
 334
 335     The returned pointer remains valid as long as \bt_p{component_class}
 336     exists.
 337     @endparblock
 338
 339 @bt_pre_not_null{component_class}
 340 */
 341 extern const char *bt_component_class_get_name(
 342                 const bt_component_class *component_class) __BT_NOEXCEPT;
 343
 344 /*!
 345 @brief
 346     Returns the description of the component class
 347     \bt_p{component_class}.
 348
 349 See the \ref api-comp-cls-prop-descr "description" property.
 350
 351 @param[in] component_class
 352     Component class of which to get the description.
 353
 354 @returns
 355     @parblock
 356     Description of \bt_p{component_class}, or \c NULL if none.
 357
 358     The returned pointer remains valid as long as \bt_p{component_class}
 359     exists.
 360     @endparblock
 361
 362 @bt_pre_not_null{component_class}
 363 */
 364 extern const char *bt_component_class_get_description(
 365                 const bt_component_class *component_class) __BT_NOEXCEPT;
 366
 367 /*!
 368 @brief
 369     Returns the help text of the component class \bt_p{component_class}.
 370
 371 See the \ref api-comp-cls-prop-help "help text" property.
 372
 373 @param[in] component_class
 374     Component class of which to get the help text.
 375
 376 @returns
 377     @parblock
 378     Help text of \bt_p{component_class}, or \c NULL if none.
 379
 380     The returned pointer remains valid as long as \bt_p{component_class}
 381     exists.
 382     @endparblock
 383
 384 @bt_pre_not_null{component_class}
 385 */
 386 extern const char *bt_component_class_get_help(
 387                 const bt_component_class *component_class) __BT_NOEXCEPT;
 388
 389 /*! @} */
 390
 391 /*!
 392 @name Common reference count
 393 @{
 394 */
 395
 396 /*!
 397 @brief
 398     Increments the \ref api-fund-shared-object "reference count" of
 399     the component class \bt_p{component_class}.
 400
 401 @param[in] component_class
 402     @parblock
 403     Component class of which to increment the reference count.
 404
 405     Can be \c NULL.
 406     @endparblock
 407
 408 @sa bt_component_put_ref() &mdash;
 409     Decrements the reference count of a component class.
 410 */
 411 extern void bt_component_class_get_ref(
 412                 const bt_component_class *component_class) __BT_NOEXCEPT;
 413
 414 /*!
 415 @brief
 416     Decrements the \ref api-fund-shared-object "reference count" of
 417     the component class \bt_p{component_class}.
 418
 419 @param[in] component_class
 420     @parblock
 421     Component class of which to decrement the reference count.
 422
 423     Can be \c NULL.
 424     @endparblock
 425
 426 @sa bt_component_get_ref() &mdash;
 427     Increments the reference count of a component class.
 428 */
 429 extern void bt_component_class_put_ref(
 430                 const bt_component_class *component_class) __BT_NOEXCEPT;
 431
 432 /*!
 433 @brief
 434     Decrements the reference count of the component class
 435     \bt_p{_component_class}, and then sets \bt_p{_component_class}
 436     to \c NULL.
 437
 438 @param _component_class
 439     @parblock
 440     Component class of which to decrement the reference count.
 441
 442     Can contain \c NULL.
 443     @endparblock
 444
 445 @bt_pre_assign_expr{_component_class}
 446 */
 447 #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class)  \
 448         do {                                                    \
 449                 bt_component_class_put_ref(_component_class);   \
 450                 (_component_class) = NULL;                      \
 451         } while (0)
 452
 453 /*!
 454 @brief
 455     Decrements the reference count of the component class \bt_p{_dst},
 456     sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
 457     to \c NULL.
 458
 459 This macro effectively moves a component class reference from the
 460 expression
 461 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 462 \bt_p{_dst} reference.
 463
 464 @param _dst
 465     @parblock
 466     Destination expression.
 467
 468     Can contain \c NULL.
 469     @endparblock
 470 @param _src
 471     @parblock
 472     Source expression.
 473
 474     Can contain \c NULL.
 475     @endparblock
 476
 477 @bt_pre_assign_expr{_dst}
 478 @bt_pre_assign_expr{_src}
 479 */
 480 #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src)         \
 481         do {                                            \
 482                 bt_component_class_put_ref(_dst);       \
 483                 (_dst) = (_src);                        \
 484                 (_src) = NULL;                          \
 485         } while (0)
 486
 487 /*! @} */
 488
 489 /*!
 490 @name Source component class upcast
 491 @{
 492 */
 493
 494 /*!
 495 @brief
 496     \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
 497     \bt_p{component_class} to the common #bt_component_class type.
 498
 499 @param[in] component_class
 500     @parblock
 501     Source component class to upcast.
 502
 503     Can be \c NULL.
 504     @endparblock
 505
 506 @returns
 507     \bt_p{component_class} as a common component class.
 508 */
 509 static inline
 510 const bt_component_class *
 511 bt_component_class_source_as_component_class_const(
 512                 const bt_component_class_source *component_class) __BT_NOEXCEPT
 513 {
 514         return __BT_UPCAST_CONST(bt_component_class, component_class);
 515 }
 516
 517 /*! @} */
 518
 519 /*!
 520 @name Source component class reference count
 521 @{
 522 */
 523
 524 /*!
 525 @brief
 526     Increments the \ref api-fund-shared-object "reference count" of
 527     the \bt_src_comp_cls \bt_p{component_class}.
 528
 529 @param[in] component_class
 530     @parblock
 531     Source component class of which to increment the reference count.
 532
 533     Can be \c NULL.
 534     @endparblock
 535
 536 @sa bt_component_class_source_put_ref() &mdash;
 537     Decrements the reference count of a source component class.
 538 */
 539 extern void bt_component_class_source_get_ref(
 540                 const bt_component_class_source *component_class) __BT_NOEXCEPT;
 541
 542 /*!
 543 @brief
 544     Decrements the \ref api-fund-shared-object "reference count" of
 545     the \bt_src_comp_cls \bt_p{component_class}.
 546
 547 @param[in] component_class
 548     @parblock
 549     Source component class of which to decrement the reference count.
 550
 551     Can be \c NULL.
 552     @endparblock
 553
 554 @sa bt_component_class_source_get_ref() &mdash;
 555     Increments the reference count of a source component class.
 556 */
 557 extern void bt_component_class_source_put_ref(
 558                 const bt_component_class_source *component_class) __BT_NOEXCEPT;
 559
 560 /*!
 561 @brief
 562     Decrements the reference count of the \bt_src_comp_cls
 563     \bt_p{_component_class}, and then sets \bt_p{_component_class} to
 564     \c NULL.
 565
 566 @param _component_class
 567     @parblock
 568     Source component class of which to decrement the reference count.
 569
 570     Can contain \c NULL.
 571     @endparblock
 572
 573 @bt_pre_assign_expr{_component_class}
 574 */
 575 #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class)   \
 576         do {                                                            \
 577                 bt_component_class_source_put_ref(_component_class);    \
 578                 (_component_class) = NULL;                              \
 579         } while (0)
 580
 581 /*!
 582 @brief
 583     Decrements the reference count of the \bt_src_comp_cls \bt_p{_dst},
 584     sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
 585     \c NULL.
 586
 587 This macro effectively moves a source component class reference from the
 588 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 589 existing \bt_p{_dst} reference.
 590
 591 @param _dst
 592     @parblock
 593     Destination expression.
 594
 595     Can contain \c NULL.
 596     @endparblock
 597 @param _src
 598     @parblock
 599     Source expression.
 600
 601     Can contain \c NULL.
 602     @endparblock
 603
 604 @bt_pre_assign_expr{_dst}
 605 @bt_pre_assign_expr{_src}
 606 */
 607 #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src)          \
 608         do {                                                    \
 609                 bt_component_class_source_put_ref(_dst);        \
 610                 (_dst) = (_src);                                \
 611                 (_src) = NULL;                                  \
 612         } while (0)
 613
 614 /*! @} */
 615
 616 /*!
 617 @name Filter component class upcast
 618 @{
 619 */
 620
 621 /*!
 622 @brief
 623     \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
 624     \bt_p{component_class} to the common #bt_component_class type.
 625
 626 @param[in] component_class
 627     @parblock
 628     Filter component class to upcast.
 629
 630     Can be \c NULL.
 631     @endparblock
 632
 633 @returns
 634     \bt_p{component_class} as a common component class.
 635 */
 636 static inline
 637 const bt_component_class *
 638 bt_component_class_filter_as_component_class_const(
 639                 const bt_component_class_filter *component_class) __BT_NOEXCEPT
 640 {
 641         return __BT_UPCAST_CONST(bt_component_class, component_class);
 642 }
 643
 644 /*! @} */
 645
 646 /*!
 647 @name Filter component class reference count
 648 @{
 649 */
 650
 651 /*!
 652 @brief
 653     Increments the \ref api-fund-shared-object "reference count" of
 654     the \bt_flt_comp_cls \bt_p{component_class}.
 655
 656 @param[in] component_class
 657     @parblock
 658     Filter component class of which to increment the reference count.
 659
 660     Can be \c NULL.
 661     @endparblock
 662
 663 @sa bt_component_class_filter_put_ref() &mdash;
 664     Decrements the reference count of a filter component class.
 665 */
 666 extern void bt_component_class_filter_get_ref(
 667                 const bt_component_class_filter *component_class) __BT_NOEXCEPT;
 668
 669 /*!
 670 @brief
 671     Decrements the \ref api-fund-shared-object "reference count" of
 672     the \bt_flt_comp_cls \bt_p{component_class}.
 673
 674 @param[in] component_class
 675     @parblock
 676     Filter component class of which to decrement the reference count.
 677
 678     Can be \c NULL.
 679     @endparblock
 680
 681 @sa bt_component_class_filter_get_ref() &mdash;
 682     Increments the reference count of a filter component class.
 683 */
 684 extern void bt_component_class_filter_put_ref(
 685                 const bt_component_class_filter *component_class) __BT_NOEXCEPT;
 686
 687 /*!
 688 @brief
 689     Decrements the reference count of the \bt_flt_comp_cls
 690     \bt_p{_component_class}, and then sets \bt_p{_component_class} to
 691     \c NULL.
 692
 693 @param _component_class
 694     @parblock
 695     Filter component class of which to decrement the reference count.
 696
 697     Can contain \c NULL.
 698     @endparblock
 699
 700 @bt_pre_assign_expr{_component_class}
 701 */
 702 #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class)   \
 703         do {                                                            \
 704                 bt_component_class_filter_put_ref(_component_class);    \
 705                 (_component_class) = NULL;                              \
 706         } while (0)
 707
 708 /*!
 709 @brief
 710     Decrements the reference count of the \bt_flt_comp_cls \bt_p{_dst},
 711     setsc \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
 712     \c NULL.
 713
 714 This macro effectively moves a filter component class reference from the
 715 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 716 existing \bt_p{_dst} reference.
 717
 718 @param _dst
 719     @parblock
 720     Destination expression.
 721
 722     Can contain \c NULL.
 723     @endparblock
 724 @param _src
 725     @parblock
 726     Source expression.
 727
 728     Can contain \c NULL.
 729     @endparblock
 730
 731 @bt_pre_assign_expr{_dst}
 732 @bt_pre_assign_expr{_src}
 733 */
 734 #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src)          \
 735         do {                                                    \
 736                 bt_component_class_filter_put_ref(_dst);        \
 737                 (_dst) = (_src);                                \
 738                 (_src) = NULL;                                  \
 739         } while (0)
 740
 741 /*! @} */
 742
 743 /*!
 744 @name Sink component class upcast
 745 @{
 746 */
 747
 748 /*!
 749 @brief
 750     \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
 751     \bt_p{component_class} to the common #bt_component_class type.
 752
 753 @param[in] component_class
 754     @parblock
 755     Sink component class to upcast.
 756
 757     Can be \c NULL.
 758     @endparblock
 759
 760 @returns
 761     \bt_p{component_class} as a common component class.
 762 */
 763 static inline
 764 const bt_component_class *
 765 bt_component_class_sink_as_component_class_const(
 766                 const bt_component_class_sink *component_class) __BT_NOEXCEPT
 767 {
 768         return __BT_UPCAST_CONST(bt_component_class, component_class);
 769 }
 770
 771 /*! @} */
 772
 773 /*!
 774 @name Sink component class reference count
 775 @{
 776 */
 777
 778 /*!
 779 @brief
 780     Increments the \ref api-fund-shared-object "reference count" of
 781     the \bt_sink_comp_cls \bt_p{component_class}.
 782
 783 @param[in] component_class
 784     @parblock
 785     Sink component class of which to increment the reference count.
 786
 787     Can be \c NULL.
 788     @endparblock
 789
 790 @sa bt_component_class_sink_put_ref() &mdash;
 791     Decrements the reference count of a sink component class.
 792 */
 793 extern void bt_component_class_sink_get_ref(
 794                 const bt_component_class_sink *component_class) __BT_NOEXCEPT;
 795
 796 /*!
 797 @brief
 798     Decrements the \ref api-fund-shared-object "reference count" of
 799     the \bt_sink_comp_cls \bt_p{component_class}.
 800
 801 @param[in] component_class
 802     @parblock
 803     Sink component class of which to decrement the reference count.
 804
 805     Can be \c NULL.
 806     @endparblock
 807
 808 @sa bt_component_class_sink_get_ref() &mdash;
 809     Increments the reference count of a sink component class.
 810 */
 811 extern void bt_component_class_sink_put_ref(
 812                 const bt_component_class_sink *component_class) __BT_NOEXCEPT;
 813
 814 /*!
 815 @brief
 816     Decrements the reference count of the \bt_sink_comp_cls
 817     \bt_p{_component_class}, and then sets \bt_p{_component_class} to
 818     \c NULL.
 819
 820 @param _component_class
 821     @parblock
 822     Sink component class of which to decrement the reference count.
 823
 824     Can contain \c NULL.
 825     @endparblock
 826
 827 @bt_pre_assign_expr{_component_class}
 828 */
 829 #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class)     \
 830         do {                                                            \
 831                 bt_component_class_sink_put_ref(_component_class);      \
 832                 (_component_class) = NULL;                              \
 833         } while (0)
 834
 835 /*!
 836 @brief
 837     Decrements the reference count of the \bt_sink_comp_cls \bt_p{_dst},
 838     sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
 839     \c NULL.
 840
 841 This macro effectively moves a sink component class reference from the
 842 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 843 existing \bt_p{_dst} reference.
 844
 845 @param _dst
 846     @parblock
 847     Destination expression.
 848
 849     Can contain \c NULL.
 850     @endparblock
 851 @param _src
 852     @parblock
 853     Source expression.
 854
 855     Can contain \c NULL.
 856     @endparblock
 857
 858 @bt_pre_assign_expr{_dst}
 859 @bt_pre_assign_expr{_src}
 860 */
 861 #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src)            \
 862         do {                                                    \
 863                 bt_component_class_sink_put_ref(_dst);          \
 864                 (_dst) = (_src);                                \
 865                 (_src) = NULL;                                  \
 866         } while (0)
 867
 868 /*! @} */
 869
 870 /*! @} */
 871
 872 #ifdef __cplusplus
 873 }
 874 #endif
 875
 876 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */