include/babeltrace2/graph/message-iterator-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_MESSAGE_ITERATOR_CLASS_H
   8 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_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 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /*!
  21 @defgroup api-msg-iter-cls Message iterator class
  22 @ingroup api-comp-cls-dev
  23
  24 @brief
  25     \bt_c_msg_iter class.
  26
  27 A <strong><em>message iterator class</em></strong> is the class of a
  28 \bt_msg_iter.
  29
  30 @image html msg-iter-cls.png
  31
  32 \bt_cp_src_comp_cls and \bt_p_flt_comp_cls contain a message iterator
  33 class. For such a component class, its message iterator class is the
  34 class of any message iterator created for any \bt_oport of the
  35 component class's instances (\bt_p_comp).
  36
  37 Therefore, the only thing you can do with a message iterator class is to
  38 pass it to bt_component_class_source_create() or
  39 bt_component_class_filter_create() to set it as the created component
  40 class's message iterator class.
  41
  42 A message iterator class has <em>methods</em>. This module essentially
  43 offers:
  44
  45 - Message iterator class method type definitions.
  46
  47 - A message iterator class creation function, to which you must pass
  48   the mandatory \link api-msg-iter-cls-meth-next "next" method\endlink.
  49
  50 - Functions to set optional message iterator class methods.
  51
  52 A message iterator class method is a user function. All message iterator
  53 class methods operate on an instance (a \bt_msg_iter). The type of the
  54 method's first parameter is #bt_self_message_iterator. This is similar
  55 to an instance method in Python (where the instance object name is
  56 generally <code>self</code>) or a member function in C++ (where the
  57 instance pointer is named <code>this</code>), for example.
  58
  59 See \ref api-msg-iter-cls-methods "Methods" to learn more about the
  60 different types of message iterator class methods.
  61
  62 A message iterator class is a
  63 \ref api-fund-shared-object "shared object": get a new reference with
  64 bt_message_iterator_class_get_ref() and put an existing reference with
  65 bt_message_iterator_class_put_ref().
  66
  67 Some library functions \ref api-fund-freezing "freeze" message iterator
  68 classes on success. The documentation of those functions indicate this
  69 postcondition.
  70
  71 The type of a message iterator class is #bt_message_iterator_class.
  72
  73 Create a message iterator class with bt_message_iterator_class_create().
  74 When you call this function, you must pass the message iterator
  75 class's mandatory
  76 \link api-msg-iter-cls-meth-next "next" method\endlink.
  77
  78 <h1>\anchor api-msg-iter-cls-methods Methods</h1>
  79
  80 To learn when exactly the methods below are called, see
  81 \ref api-graph-lc "Trace processing graph life cycle" and
  82 \ref api-msg-iter.
  83
  84 The available message iterator class methods to implement are:
  85
  86 <table>
  87   <tr>
  88     <th>Name
  89     <th>Requirement
  90     <th>C type
  91   <tr>
  92     <td>Can seek beginning?
  93     <td>Optional
  94     <td>#bt_message_iterator_class_can_seek_beginning_method
  95   <tr>
  96     <td>Can seek ns from origin?
  97     <td>Optional
  98     <td>#bt_message_iterator_class_can_seek_ns_from_origin_method
  99   <tr>
 100     <td>Finalize
 101     <td>Optional
 102     <td>#bt_message_iterator_class_finalize_method
 103   <tr>
 104     <td>Initialize
 105     <td>Optional
 106     <td>#bt_message_iterator_class_initialize_method
 107   <tr>
 108     <td>Next
 109     <td>Mandatory
 110     <td>#bt_message_iterator_class_next_method
 111   <tr>
 112     <td>Seek beginning
 113     <td>Optional
 114     <td>#bt_message_iterator_class_seek_beginning_method
 115   <tr>
 116     <td>Seek ns from origin
 117     <td>Optional
 118     <td>#bt_message_iterator_class_seek_ns_from_origin_method
 119 </table>
 120
 121 <dl>
 122   <dt>
 123     \anchor api-msg-iter-cls-meth-can-seek-beg
 124     Can seek beginning?
 125   </dt>
 126   <dd>
 127     Called to check whether or not your \bt_msg_iter can currently
 128     seek its beginning (the very first message of its
 129     \ref api-msg-seq "sequence").
 130
 131     There are some use cases in which a message iterator cannot always
 132     seek its beginning, depending on its state.
 133
 134     If you don't implement this method, then, if you implement the
 135     \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method, the
 136     library assumes that your message iterator can always seek its
 137     beginning.
 138
 139     The message iterator of a \bt_flt_comp will typically consider
 140     the beginning seeking capability of its own upstream message
 141     iterator(s) (with bt_message_iterator_can_seek_beginning()) in this
 142     method's implementation.
 143
 144     If you need to block the thread to compute whether or not your
 145     message iterator can seek its beginning, you can instead report to
 146     try again later to the caller by returning
 147     #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
 148
 149     Set this optional method with the \bt_p{can_seek_method} parameter
 150     of bt_message_iterator_class_set_seek_beginning_methods().
 151   </dd>
 152
 153   <dt>
 154     \anchor api-msg-iter-cls-meth-can-seek-ns
 155     Can seek ns from origin?
 156   </dt>
 157   <dd>
 158     Called to check whether or not your \bt_msg_iter can currently
 159     seek a message occurring at or after a specific time given in
 160     nanoseconds from its
 161     \ref api-tir-clock-cls-origin "clock class origin".
 162
 163     There are some use cases in which a message iterator cannot always
 164     seek some specific time, depending on its state.
 165
 166     Within this method, your receive the specific time to seek as the
 167     \bt_p{ns_from_origin} parameter. You don't receive any
 168     \bt_clock_cls: the method operates at the nanosecond from some
 169     origin level and it is left to the implementation to decide whether
 170     or not the message iterator can seek this point in time.
 171
 172     If you don't implement this method, then, if you implement the
 173     \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method, the
 174     library assumes that your message iterator can always seek any
 175     message occurring at or after any time.
 176
 177     The message iterator of a \bt_flt_comp will typically consider
 178     the time seeking capability of its own upstream message
 179     iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in
 180     this method's implementation.
 181
 182     If you need to block the thread to compute whether or not your
 183     message iterator can seek a message occurring at or after a given
 184     time, you can instead report to try again later to the caller by
 185     returning
 186     #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
 187
 188     Set this optional method with the \bt_p{can_seek_method} parameter
 189     of bt_message_iterator_class_set_seek_ns_from_origin_methods().
 190   </dd>
 191
 192   <dt>
 193     \anchor api-msg-iter-cls-meth-fini
 194     Finalize
 195   </dt>
 196   <dd>
 197     Called to finalize your \bt_msg_iter, that is, to let you
 198     destroy/free/finalize any user data you have (retrieved with
 199     bt_self_message_iterator_get_data()).
 200
 201     The \bt_name library does not specify exactly when this method is
 202     called, but guarantees that it's called before the message iterator
 203     is destroyed.
 204
 205     The library guarantees that all message iterators are destroyed
 206     before their component is destroyed.
 207
 208     This method is \em not called if the message iterator's
 209     \ref api-msg-iter-cls-meth-init "initialization method"
 210     previously returned an error status code.
 211
 212     Set this optional method with
 213     bt_message_iterator_class_set_finalize_method().
 214   </dd>
 215
 216   <dt>
 217     \anchor api-msg-iter-cls-meth-init
 218     Initialize
 219   </dt>
 220   <dd>
 221     Called within bt_message_iterator_create_from_message_iterator()
 222     or bt_message_iterator_create_from_sink_component() to initialize
 223     your \bt_msg_iter.
 224
 225     Within this method, you can access your \bt_comp's user data
 226     by first borrowing it with
 227     bt_self_message_iterator_borrow_component() and then using
 228     bt_self_component_get_data().
 229
 230     For the message iterator of a \bt_flt_comp, this method is
 231     typically where you create an upstream \bt_msg_iter
 232     with bt_message_iterator_create_from_message_iterator().
 233
 234     You can create user data and set it as the \bt_self_msg_iter's user
 235     data with bt_self_message_iterator_set_data().
 236
 237     If you return #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
 238     from this method, then your message iterator's
 239     \ref api-msg-iter-cls-meth-fini "finalization method" will be
 240     called, if it exists, when your message iterator is finalized.
 241
 242     This method receives a message iterator configuration object
 243     (#bt_self_message_iterator_configuration type). As of
 244     \bt_name_version_min_maj, you can use
 245     bt_self_message_iterator_configuration_set_can_seek_forward()
 246     during, and only during, this method's execution to set whether or
 247     not your message iterator can <em>seek forward</em>.
 248
 249     For a message iterator to be able to seek forward, all the \bt_p_msg
 250     of its message sequence must have some \bt_cs.
 251     bt_message_iterator_seek_ns_from_origin() uses this configuration
 252     option and the beginning seeking capability of a message iterator
 253     (bt_message_iterator_can_seek_beginning())
 254     to make it seek a message occurring at or after a specific time even
 255     when the message iterator does not implement the
 256     \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
 257
 258     Set this optional method with
 259     bt_message_iterator_class_set_initialize_method().
 260   </dd>
 261
 262   <dt>
 263     \anchor api-msg-iter-cls-meth-next
 264     "Next" (get next messages)
 265   </dt>
 266   <dd>
 267     Called within bt_message_iterator_next()
 268     to "advance" your \bt_msg_iter, that is, to get its next
 269     messages.
 270
 271     Within this method, you receive:
 272
 273     - An array of \bt_p_msg to fill (\bt_p{messages} parameter)
 274       with your message iterator's next messages, if any.
 275
 276       Note that this array needs its own message
 277       \ref api-fund-shared-object "references". In other
 278       words, if you have a message reference and you put this message
 279       into the array without calling bt_message_get_ref(), then you just
 280       \em moved the message reference to the array (the array owns the
 281       message now).
 282
 283     - The capacity of the message array (\bt_p{capacity} parameter),
 284       that is, the maximum number of messages you can put in it.
 285
 286     - A message count output parameter (\bt_p{count}) which, on success,
 287       you must set to the number of messages you put in the message
 288       array.
 289
 290     If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
 291     from this method, then you must put at least one message in the
 292     message array. In other words, \bt_p{*count} must be greater than
 293     zero.
 294
 295     You must honour the \ref api-msg-seq "message sequence rules" when
 296     you put new or existing messages in the message array.
 297
 298     If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
 299     then all the messages of the message array become
 300     \ref api-fund-freezing "frozen".
 301
 302     This method typically:
 303
 304     <dl>
 305       <dt>For a \bt_src_comp's message iterator</dt>
 306       <dd>
 307         Creates brand new \bt_p_msg to represent one or more input
 308         traces.
 309       </dd>
 310
 311       <dt>For a \bt_flt_comp's message iterator</dt>
 312       <dd>
 313         Gets \em one message batch from one (or more) upstream
 314         \bt_msg_iter and filters them.
 315       </dd>
 316     </dl>
 317
 318     For a source component's message iterator, you are free to create
 319     as many as \bt_p{capacity} messages. For a filter component's
 320     message iterator, you are free to get more than one batch of
 321     messages from upstream message iterators if needed. However, in both
 322     cases, keep in mind that the \bt_name project recommends that this
 323     method executes fast enough so as not to block an interactive
 324     application running on the same thread.
 325
 326     During what you consider to be a long, blocking operation, the
 327     project recommends that you periodically check whether or not you
 328     are interrupted with bt_self_message_iterator_is_interrupted(). When
 329     you are, you can return either
 330     #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or
 331     #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on
 332     your capability to continue the current operation later.
 333
 334     If you need to block the thread to insert messages into the message
 335     array, you can instead report to try again later to the caller by
 336     returning #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN.
 337     When you return this status code, you must \em not put any message
 338     into the message array.
 339
 340     If your message iterator's iteration process is done (you have no
 341     more messages to emit), then return
 342     #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return
 343     this status code, you must \em not put any message into the message
 344     array.
 345
 346     Set this mandatory method at message iterator class creation time
 347     with bt_message_iterator_class_create().
 348   </dd>
 349
 350   <dt>
 351     \anchor api-msg-iter-cls-meth-seek-beg
 352     Seek beginning
 353   </dt>
 354   <dd>
 355     Called within bt_message_iterator_seek_beginning() to make
 356     your message iterator seek its beginning, that is, the very first
 357     message of its \ref api-msg-seq "sequence".
 358
 359     The sequence of messages of a given message iterator must always be
 360     the same, in that, if your message iterator emitted the messages A,
 361     B, C, D, and E, and then this "seek beginning" method is called
 362     successfully
 363     (it returns
 364     #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK),
 365     then your message iterator's next messages (the next time your
 366     \link api-msg-iter-cls-meth-next "next" method\endlink
 367     is called) must be A, B, C, D, and E.
 368
 369     The \bt_name project recommends that this method executes fast
 370     enough so as not to block an interactive application running on the
 371     same thread.
 372
 373     During what you consider to be a long, blocking operation, the
 374     project recommends that you periodically check whether or not you
 375     are interrupted with bt_self_message_iterator_is_interrupted(). When
 376     you are, you can return either
 377     #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or
 378     #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR,
 379     depending on your capability to continue the current operation
 380     later.
 381
 382     If you need to block the thread to make your message iterator seek
 383     its beginning, you can instead report to try again later to the
 384     caller by returning
 385     #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
 386
 387     The optional
 388     \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
 389     method can indicate whether or not your message iterator can
 390     currently seek its beginning. If you implement it, the library
 391     guarantees that it is called and returns #BT_TRUE before this "seek
 392     beginning" is called, without any other message iterator methods
 393     being called in between.
 394
 395     Set this optional method with the \bt_p{seek_method} parameter
 396     of bt_message_iterator_class_set_seek_beginning_methods().
 397   </dd>
 398
 399   <dt>
 400     \anchor api-msg-iter-cls-meth-seek-ns
 401     Seek ns from origin
 402   </dt>
 403   <dd>
 404     Called within bt_message_iterator_seek_ns_from_origin() to make
 405     your message iterator seek a message occurring at or after a specific
 406     time given in nanoseconds from its
 407     \ref api-tir-clock-cls-origin "clock class origin".
 408
 409     Within this method, your receive the specific time to seek as the
 410     \bt_p{ns_from_origin} parameter. You don't receive any
 411     \bt_clock_cls: the method operates at the nanosecond from some
 412     origin level and it is left to the implementation to seek a message
 413     having at least this time while still honouring the
 414     \ref api-msg-seq "message sequence rules" the next time your
 415     \link api-msg-iter-cls-meth-next "next" method\endlink is called.
 416
 417     If you return
 418     #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from
 419     this method, then the next time your
 420     \link api-msg-iter-cls-meth-next "next" method\endlink is called:
 421
 422     - For each "active" \bt_stream at the seeked time point, you must
 423       emit a \bt_sb_msg for this stream before you emit any other
 424       message for this stream.
 425
 426       The stream beginning message must have a
 427       \ref api-msg-sb-prop-cs "default clock snapshot" which corresponds
 428       to the seeked time point.
 429
 430     - For each "active" \bt_pkt at the seeked time point, you must
 431       emit a \bt_pb_msg for this packet before you emit any other
 432       message for this packet.
 433
 434       The packet beginning message must have a
 435       \ref api-msg-pb-prop-cs "default clock snapshot" which corresponds
 436       to the seeked time point.
 437
 438     The \bt_name project recommends that this method executes fast
 439     enough so as not to block an interactive application running on the
 440     same thread.
 441
 442     During what you consider to be a long, blocking operation, the
 443     project recommends that you periodically check whether or not you
 444     are interrupted with bt_self_message_iterator_is_interrupted(). When
 445     you are, you can return either
 446     #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
 447     or
 448     #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR,
 449     depending on your capability to continue the current operation
 450     later.
 451
 452     If you need to block the thread to make your message iterator seek a
 453     message occurring at or after a given time, you can instead report to
 454     try again later to the caller by returning
 455     #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
 456
 457     The optional
 458     \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
 459     method can indicate whether or not your message iterator can
 460     currently seek a specific time. If you implement it, the library
 461     guarantees that it is called and returns #BT_TRUE before this "seek
 462     ns from origin" is called, without any other message iterator
 463     methods being called in between.
 464
 465     Set this optional method with the \bt_p{seek_method} parameter
 466     of bt_message_iterator_class_set_seek_ns_from_origin_methods().
 467   </dd>
 468 </dl>
 469
 470 Within any method, you can access the \bt_msg_iter's \bt_comp's
 471 configured \ref #bt_logging_level "logging level" by first upcasting the
 472 \bt_self_comp to the #bt_component type with
 473 bt_self_component_as_component(), and then with
 474 bt_component_get_logging_level().
 475 */
 476
 477 /*! @{ */
 478
 479 /*!
 480 @name Type
 481 @{
 482
 483 @typedef struct bt_message_iterator_class bt_message_iterator_class;
 484
 485 @brief
 486     Message iterator class.
 487
 488 @}
 489 */
 490
 491 /*!
 492 @name Method types
 493 @{
 494 */
 495
 496 /*!
 497 @brief
 498     Status codes for #bt_message_iterator_class_can_seek_beginning_method.
 499 */
 500 typedef enum bt_message_iterator_class_can_seek_beginning_method_status {
 501         /*!
 502         @brief
 503             Success.
 504         */
 505         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK           = __BT_FUNC_STATUS_OK,
 506
 507         /*!
 508         @brief
 509             Try again.
 510         */
 511         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN        = __BT_FUNC_STATUS_AGAIN,
 512
 513         /*!
 514         @brief
 515             Out of memory.
 516         */
 517         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 518
 519         /*!
 520         @brief
 521             User error.
 522         */
 523         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
 524 } bt_message_iterator_class_can_seek_beginning_method_status;
 525
 526 /*!
 527 @brief
 528     \bt_c_msg_iter "can seek beginning?" method.
 529
 530 See the \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
 531 method.
 532
 533 @param[in] self_message_iterator
 534     Message iterator instance.
 535 @param[out] can_seek_beginning
 536     <strong>On success</strong>, \bt_p{*can_seek_beginning} is
 537     #BT_TRUE if \bt_p{self_message_iterator} can currently seek its
 538     beginning.
 539
 540 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
 541     Success.
 542 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
 543     Try again.
 544 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
 545     Out of memory.
 546 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
 547     User error.
 548
 549 @bt_pre_not_null{self_message_iterator}
 550 @bt_pre_not_null{can_seek_beginning}
 551
 552 @post
 553     <strong>On success</strong>, \bt_p{*can_seek_beginning} is set.
 554
 555 @sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
 556     Sets the "seek beginning" and "can seek beginning?" methods of a
 557     message iterator class.
 558 */
 559 typedef bt_message_iterator_class_can_seek_beginning_method_status
 560 (*bt_message_iterator_class_can_seek_beginning_method)(
 561                 bt_self_message_iterator *self_message_iterator,
 562                 bt_bool *can_seek_beginning);
 563
 564 /*!
 565 @brief
 566     Status codes for #bt_message_iterator_class_can_seek_ns_from_origin_method.
 567 */
 568 typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status {
 569         /*!
 570         @brief
 571             Success.
 572         */
 573         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK              = __BT_FUNC_STATUS_OK,
 574
 575         /*!
 576         @brief
 577             Try again.
 578         */
 579         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN           = __BT_FUNC_STATUS_AGAIN,
 580
 581         /*!
 582         @brief
 583             Out of memory.
 584         */
 585         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 586
 587         /*!
 588         @brief
 589             User error.
 590         */
 591         BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
 592 } bt_message_iterator_class_can_seek_ns_from_origin_method_status;
 593
 594 /*!
 595 @brief
 596     \bt_c_msg_iter "can seek ns from origin?" method.
 597
 598 See the \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
 599 method.
 600
 601 @param[in] self_message_iterator
 602     Message iterator instance.
 603 @param[in] ns_from_origin
 604     Requested time point to seek.
 605 @param[out] can_seek_ns_from_origin
 606     <strong>On success</strong>, set \bt_p{*can_seek_ns_from_origin} to
 607     #BT_TRUE if \bt_p{self_message_iterator} can currently seek a
 608     message occurring at or after \bt_p{ns_from_origin} nanoseconds from
 609     its \ref api-tir-clock-cls-origin "clock class origin".
 610
 611 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
 612     Success.
 613 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
 614     Try again.
 615 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
 616     Out of memory.
 617 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
 618     User error.
 619
 620 @bt_pre_not_null{self_message_iterator}
 621 @bt_pre_not_null{can_seek_ns_from_origin}
 622
 623 @post
 624     <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is set.
 625
 626 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
 627     Sets the "seek ns from origin" and "can seek ns from origin?"
 628     methods of a message iterator class.
 629 */
 630 typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
 631 (*bt_message_iterator_class_can_seek_ns_from_origin_method)(
 632                 bt_self_message_iterator *self_message_iterator,
 633                 int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
 634
 635 /*!
 636 @brief
 637     \bt_c_msg_iter finalization method.
 638
 639 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
 640
 641 @param[in] self_message_iterator
 642     Message iterator instance.
 643
 644 @bt_pre_not_null{self_message_iterator}
 645
 646 @bt_post_no_error
 647
 648 @sa bt_message_iterator_class_set_finalize_method() &mdash;
 649     Sets the finalization method of a message iterator class.
 650 */
 651 typedef void
 652 (*bt_message_iterator_class_finalize_method)(
 653                 bt_self_message_iterator *self_message_iterator);
 654
 655 /*!
 656 @brief
 657     Status codes for #bt_message_iterator_class_initialize_method.
 658 */
 659 typedef enum bt_message_iterator_class_initialize_method_status {
 660         /*!
 661         @brief
 662             Success.
 663         */
 664         BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK           = __BT_FUNC_STATUS_OK,
 665
 666         /*!
 667         @brief
 668             Out of memory.
 669         */
 670         BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 671
 672         /*!
 673         @brief
 674             User error.
 675         */
 676         BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
 677 } bt_message_iterator_class_initialize_method_status;
 678
 679 /*!
 680 @brief
 681     \bt_c_msg_iter initialization method.
 682
 683 See the \ref api-msg-iter-cls-meth-init "initialize" method.
 684
 685 @param[in] self_message_iterator
 686     Message iterator instance.
 687 @param[in] configuration
 688     Message iterator's configuration.
 689 @param[in] port
 690     \bt_c_oport for which \bt_p{self_message_iterator} was created.
 691
 692 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
 693     Success.
 694 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
 695     Out of memory.
 696 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR
 697     User error.
 698
 699 @bt_pre_not_null{self_message_iterator}
 700 @bt_pre_not_null{configuration}
 701 @bt_pre_not_null{port}
 702
 703 @sa bt_message_iterator_class_set_initialize_method() &mdash;
 704     Sets the initialization method of a message iterator class.
 705 */
 706 typedef bt_message_iterator_class_initialize_method_status
 707 (*bt_message_iterator_class_initialize_method)(
 708                 bt_self_message_iterator *self_message_iterator,
 709                 bt_self_message_iterator_configuration *configuration,
 710                 bt_self_component_port_output *port);
 711
 712 /*!
 713 @brief
 714     Status codes for #bt_message_iterator_class_next_method.
 715 */
 716 typedef enum bt_message_iterator_class_next_method_status {
 717         /*!
 718         @brief
 719             Success.
 720         */
 721         BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK                 = __BT_FUNC_STATUS_OK,
 722
 723         /*!
 724         @brief
 725             End of iteration.
 726         */
 727         BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END                = __BT_FUNC_STATUS_END,
 728
 729         /*!
 730         @brief
 731             Try again.
 732         */
 733         BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN              = __BT_FUNC_STATUS_AGAIN,
 734
 735         /*!
 736         @brief
 737             Out of memory.
 738         */
 739         BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
 740
 741         /*!
 742         @brief
 743             User error.
 744         */
 745         BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
 746 } bt_message_iterator_class_next_method_status;
 747
 748 /*!
 749 @brief
 750     \bt_c_msg_iter "next" (get next messages) method.
 751
 752 See the \link api-msg-iter-cls-meth-next "next"\endlink method.
 753
 754 If this method returns #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
 755 then all the messages of the message array become
 756 \ref api-fund-freezing "frozen".
 757
 758 @param[in] self_message_iterator
 759     Message iterator instance.
 760 @param[out] messages
 761     @parblock
 762     Message array to fill, on success, with the \bt_p_msg to emit.
 763
 764     This array needs its own message
 765     \ref api-fund-shared-object "references". In other
 766     words, if you have a message reference and you put this message
 767     into the array without calling bt_message_get_ref(), then you just
 768     \em moved the message reference to the array (the array owns the
 769     message now).
 770
 771     The capacity of this array (maximum number of messages you can put
 772     in it) is \bt_p{capacity}.
 773     @endparblock
 774 @param[in] capacity
 775     Capacity of the \bt_p{messages} array (maximum number of messages
 776     you can put in it).
 777 @param[out] count
 778     <strong>On success</strong>, \bt_p{*count} is the number of messages
 779     you put in \bt_p{messages}.
 780
 781 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
 782     Success.
 783 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END
 784     End of iteration.
 785 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN
 786     Try again.
 787 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR
 788     Out of memory.
 789 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR
 790     User error.
 791
 792 @bt_pre_not_null{self_message_iterator}
 793 @bt_pre_not_null{messages}
 794 @pre
 795     \bt_p{capacity} ≥ 1.
 796 @bt_pre_not_null{count}
 797
 798 @post
 799     <strong>On success</strong>, \bt_p{messages} contains \bt_p{*count}
 800     message references as its first \bt_p{*count} elements.
 801 @post
 802     <strong>On success</strong>, the \bt_p_msg in \bt_p{messages} honour
 803     the \ref api-msg-seq "message sequence rules".
 804 @post
 805     <strong>On success</strong>, for any \bt_ev_msg in
 806     \bt_p{messages}, its
 807     \ref api-tir-ev-prop-payload "payload field",
 808     \ref api-tir-ev-prop-spec-ctx "specific context field",
 809     \ref api-tir-ev-prop-common-ctx "common context field", and all
 810     their inner \bt_p_field, recursively, are set.
 811 @post
 812     <strong>On success</strong>, \bt_p{*count}&nbsp;≥&nbsp;1.
 813 @post
 814     <strong>On success</strong>,
 815     \bt_p{*count}&nbsp;≤&nbsp;\bt_p{capacity}.
 816
 817 @sa bt_message_iterator_class_create() &mdash;
 818     Creates a message iterator class.
 819 */
 820 typedef bt_message_iterator_class_next_method_status
 821 (*bt_message_iterator_class_next_method)(
 822                 bt_self_message_iterator *self_message_iterator,
 823                 bt_message_array_const messages, uint64_t capacity,
 824                 uint64_t *count);
 825
 826 /*!
 827 @brief
 828     Status codes for #bt_message_iterator_class_seek_beginning_method.
 829 */
 830 typedef enum bt_message_iterator_class_seek_beginning_method_status {
 831         /*!
 832         @brief
 833             Success.
 834         */
 835         BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK               = __BT_FUNC_STATUS_OK,
 836
 837         /*!
 838         @brief
 839             Try again.
 840         */
 841         BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
 842
 843         /*!
 844         @brief
 845             Out of memory.
 846         */
 847         BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 848
 849         /*!
 850         @brief
 851             User error.
 852         */
 853         BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 854 } bt_message_iterator_class_seek_beginning_method_status;
 855
 856 /*!
 857 @brief
 858     \bt_c_msg_iter "seek beginning" method.
 859
 860 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method.
 861
 862 @param[in] self_message_iterator
 863     Message iterator instance.
 864
 865 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK
 866     Success.
 867 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN
 868     Try again.
 869 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
 870     Out of memory.
 871 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR
 872     User error.
 873
 874 @bt_pre_not_null{self_message_iterator}
 875 @pre
 876     <strong>If \bt_p{self_message_iterator} has a
 877     \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
 878     method</strong>, then it was called and returned #BT_TRUE before
 879     this "seek beginning" method is called, without any other method of
 880     \bt_p{self_message_iterator} called in between.
 881
 882 @sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
 883     Sets the "seek beginning" and "can seek beginning?" methods of a
 884     message iterator class.
 885 */
 886 typedef bt_message_iterator_class_seek_beginning_method_status
 887 (*bt_message_iterator_class_seek_beginning_method)(
 888                 bt_self_message_iterator *self_message_iterator);
 889
 890 /*!
 891 @brief
 892     Status codes for #bt_message_iterator_class_seek_ns_from_origin_method.
 893 */
 894 typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status {
 895         /*!
 896         @brief
 897             Success.
 898         */
 899         BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 900
 901         /*!
 902         @brief
 903             Try again.
 904         */
 905         BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN               = __BT_FUNC_STATUS_AGAIN,
 906
 907         /*!
 908         @brief
 909             Out of memory.
 910         */
 911         BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
 912
 913         /*!
 914         @brief
 915             User error.
 916         */
 917         BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
 918 } bt_message_iterator_class_seek_ns_from_origin_method_status;
 919
 920 /*!
 921 @brief
 922     \bt_c_msg_iter "seek ns from origin" method.
 923
 924 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
 925
 926 @param[in] self_message_iterator
 927     Message iterator instance.
 928 @param[in] ns_from_origin
 929     Time point to seek.
 930
 931 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
 932     Success.
 933 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
 934     Try again.
 935 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
 936     Out of memory.
 937 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
 938     User error.
 939
 940 @bt_pre_not_null{self_message_iterator}
 941 @pre
 942     <strong>If \bt_p{self_message_iterator} has a
 943     \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
 944     method</strong>, then it was called and returned #BT_TRUE before
 945     this "seek ns from origin" method is called, without any other
 946     method of \bt_p{self_message_iterator} called in between.
 947
 948 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
 949     Sets the "seek ns from origin" and "can seek ns from origin?"
 950     methods of a message iterator class.
 951 */
 952 typedef bt_message_iterator_class_seek_ns_from_origin_method_status
 953 (*bt_message_iterator_class_seek_ns_from_origin_method)(
 954                 bt_self_message_iterator *self_message_iterator,
 955                 int64_t ns_from_origin);
 956
 957 /*! @} */
 958
 959 /*!
 960 @name Creation
 961 @{
 962 */
 963
 964 /*!
 965 @brief
 966     Creates a message iterator class having the
 967     \link api-msg-iter-cls-meth-next "next" method\endlink method
 968     \bt_p{next_method}.
 969
 970 @param[in] next_method
 971     "Next" method of the message iterator class to create.
 972
 973 @returns
 974     New message iterator class reference, or \c NULL on memory error.
 975
 976 @bt_pre_not_null{next_method}
 977 */
 978 extern bt_message_iterator_class *
 979 bt_message_iterator_class_create(
 980                 bt_message_iterator_class_next_method next_method)
 981                 __BT_NOEXCEPT;
 982
 983 /*! @} */
 984
 985 /*!
 986 @name Method setting
 987 @{
 988 */
 989
 990 /*!
 991 @brief
 992     Status code for the
 993     <code>bt_message_iterator_class_set_*_method()</code> functions.
 994 */
 995 typedef enum bt_message_iterator_class_set_method_status {
 996         /*!
 997         @brief
 998             Success.
 999         */
1000         BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK  = __BT_FUNC_STATUS_OK,
1001 } bt_message_iterator_class_set_method_status;
1002
1003 /*!
1004 @brief
1005     Sets the optional finalization method of the message iterator class
1006     \bt_p{message_iterator_class} to \bt_p{method}.
1007
1008 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
1009
1010 @param[in] message_iterator_class
1011     Message iterator class of which to set the finalization method to
1012     \bt_p{method}.
1013 @param[in] method
1014     New finalization method of \bt_p{message_iterator_class}.
1015
1016 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1017     Success.
1018
1019 @bt_pre_not_null{message_iterator_class}
1020 @bt_pre_hot{message_iterator_class}
1021 @bt_pre_not_null{method}
1022 */
1023 extern bt_message_iterator_class_set_method_status
1024 bt_message_iterator_class_set_finalize_method(
1025                 bt_message_iterator_class *message_iterator_class,
1026                 bt_message_iterator_class_finalize_method method) __BT_NOEXCEPT;
1027
1028 /*!
1029 @brief
1030     Sets the optional initialization method of the message iterator
1031     class \bt_p{message_iterator_class} to \bt_p{method}.
1032
1033 See the \ref api-msg-iter-cls-meth-init "initialize" method.
1034
1035 @param[in] message_iterator_class
1036     Message iterator class of which to set the initialization method to
1037     \bt_p{method}.
1038 @param[in] method
1039     New initialization method of \bt_p{message_iterator_class}.
1040
1041 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1042     Success.
1043
1044 @bt_pre_not_null{message_iterator_class}
1045 @bt_pre_hot{message_iterator_class}
1046 @bt_pre_not_null{method}
1047 */
1048 extern bt_message_iterator_class_set_method_status
1049 bt_message_iterator_class_set_initialize_method(
1050                 bt_message_iterator_class *message_iterator_class,
1051                 bt_message_iterator_class_initialize_method method)
1052                 __BT_NOEXCEPT;
1053
1054 /*!
1055 @brief
1056     Sets the optional "seek beginning" and
1057     "can seek beginning?" methods of the message iterator class
1058     \bt_p{message_iterator_class} to \bt_p{seek_method} and
1059     \bt_p{can_seek_method}.
1060
1061 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning"
1062 and \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
1063 methods.
1064
1065 @param[in] message_iterator_class
1066     Message iterator class of which to set the "seek beginning"
1067     and "can seek beginning?" methods.
1068 @param[in] seek_method
1069     New "seek beginning" method of \bt_p{message_iterator_class}.
1070 @param[in] can_seek_method
1071     @parblock
1072     New "can seek beginning?" method of \bt_p{message_iterator_class}.
1073
1074     Can be \c NULL, in which case it is equivalent to setting a method
1075     which always returns #BT_TRUE.
1076     @endparblock
1077
1078 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1079     Success.
1080
1081 @bt_pre_not_null{message_iterator_class}
1082 @bt_pre_hot{message_iterator_class}
1083 @bt_pre_not_null{seek_method}
1084 */
1085 extern bt_message_iterator_class_set_method_status
1086 bt_message_iterator_class_set_seek_beginning_methods(
1087                 bt_message_iterator_class *message_iterator_class,
1088                 bt_message_iterator_class_seek_beginning_method seek_method,
1089                 bt_message_iterator_class_can_seek_beginning_method can_seek_method)
1090                 __BT_NOEXCEPT;
1091
1092 /*!
1093 @brief
1094     Sets the optional "seek ns from origin" and
1095     "can seek ns from origin?" methods of the message iterator class
1096     \bt_p{message_iterator_class} to \bt_p{seek_method} and
1097     \bt_p{can_seek_method}.
1098
1099 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin"
1100 and
1101 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
1102 methods.
1103
1104 @param[in] message_iterator_class
1105     Message iterator class of which to set the "seek ns from origin"
1106     and "can seek ns from origin?" methods.
1107 @param[in] seek_method
1108     New "seek ns from origin" method of \bt_p{message_iterator_class}.
1109 @param[in] can_seek_method
1110     @parblock
1111     New "can seek ns from origin?" method of
1112     \bt_p{message_iterator_class}.
1113
1114     Can be \c NULL, in which case it is equivalent to setting a method
1115     which always returns #BT_TRUE.
1116     @endparblock
1117
1118 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1119     Success.
1120
1121 @bt_pre_not_null{message_iterator_class}
1122 @bt_pre_hot{message_iterator_class}
1123 @bt_pre_not_null{seek_method}
1124 */
1125 extern bt_message_iterator_class_set_method_status
1126 bt_message_iterator_class_set_seek_ns_from_origin_methods(
1127                 bt_message_iterator_class *message_iterator_class,
1128                 bt_message_iterator_class_seek_ns_from_origin_method seek_method,
1129                 bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method)
1130                 __BT_NOEXCEPT;
1131
1132 /*! @} */
1133
1134 /*!
1135 @name Reference count
1136 @{
1137 */
1138
1139 /*!
1140 @brief
1141     Increments the \ref api-fund-shared-object "reference count" of
1142     the message iterator class \bt_p{message_iterator_class}.
1143
1144 @param[in] message_iterator_class
1145     @parblock
1146     Message iterator class of which to increment the reference count.
1147
1148     Can be \c NULL.
1149     @endparblock
1150
1151 @sa bt_component_put_ref() &mdash;
1152     Decrements the reference count of a message iterator class.
1153 */
1154 extern void bt_message_iterator_class_get_ref(
1155                 const bt_message_iterator_class *message_iterator_class)
1156                 __BT_NOEXCEPT;
1157
1158 /*!
1159 @brief
1160     Decrements the \ref api-fund-shared-object "reference count" of
1161     the message iterator class \bt_p{message_iterator_class}.
1162
1163 @param[in] message_iterator_class
1164     @parblock
1165     Message iterator class of which to decrement the reference count.
1166
1167     Can be \c NULL.
1168     @endparblock
1169
1170 @sa bt_component_get_ref() &mdash;
1171     Increments the reference count of a message iterator class.
1172 */
1173 extern void bt_message_iterator_class_put_ref(
1174                 const bt_message_iterator_class *message_iterator_class)
1175                 __BT_NOEXCEPT;
1176
1177 /*!
1178 @brief
1179     Decrements the reference count of the message iterator class
1180     \bt_p{_message_iterator_class}, and then sets
1181     \bt_p{_message_iterator_class} to \c NULL.
1182
1183 @param _message_iterator_class
1184     @parblock
1185     Message iterator class of which to decrement the reference count.
1186
1187     Can contain \c NULL.
1188     @endparblock
1189
1190 @bt_pre_assign_expr{_message_iterator_class}
1191 */
1192 #define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_message_iterator_class) \
1193         do {                                                            \
1194                 bt_message_iterator_class_put_ref(_message_iterator_class); \
1195                 (_message_iterator_class) = NULL;                       \
1196         } while (0)
1197
1198 /*!
1199 @brief
1200     Decrements the reference count of the message iterator class \bt_p{_dst},
1201     sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
1202     to \c NULL.
1203
1204 This macro effectively moves a message iterator class reference from the
1205 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1206 existing \bt_p{_dst} reference.
1207
1208 @param _dst
1209     @parblock
1210     Destination expression.
1211
1212     Can contain \c NULL.
1213     @endparblock
1214 @param _src
1215     @parblock
1216     Source expression.
1217
1218     Can contain \c NULL.
1219     @endparblock
1220
1221 @bt_pre_assign_expr{_dst}
1222 @bt_pre_assign_expr{_src}
1223 */
1224 #define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_dst, _src)     \
1225         do {                                                    \
1226                 bt_message_iterator_class_put_ref(_dst);        \
1227                 (_dst) = (_src);                                \
1228                 (_src) = NULL;                                  \
1229         } while (0)
1230
1231 /*! @} */
1232
1233 /*! @} */
1234
1235 #ifdef __cplusplus
1236 }
1237 #endif
1238
1239 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H */