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