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