include/babeltrace2/graph/component-class.h

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