include/babeltrace2/graph/message-iterator-class.h

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