include/babeltrace2/graph/message-iterator.h

   1 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
   2 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /*!
  35 @defgroup api-msg-iter Message iterator
  36 @ingroup api-comp-cls-dev
  37
  38 @brief
  39     Iterator of a \bt_msg sequence.
  40
  41 A <strong><em>message iterator</em></strong> iterates a sequence of
  42 \bt_p_msg.
  43
  44 A message iterator is the \bt_name mechanism for the \bt_p_comp of a
  45 trace processing \bt_graph to exchange information. This information
  46 takes the form of a sequence of individual messages which contain
  47 trace data (\bt_p_ev, for example).
  48
  49 A message iterator is a \bt_msg_iter_cls instance. Because a message
  50 iterator class is part of a \bt_src_comp_cls or \bt_flt_comp_cls, a
  51 message iterator is part of a \bt_src_comp or \bt_flt_comp. Borrow
  52 a message iterator's component with
  53 bt_message_iterator_borrow_component().
  54
  55 A message iterator is a \ref api-fund-shared-object "shared object": get
  56 a new reference with bt_component_get_ref() and put an existing
  57 reference with bt_component_put_ref().
  58
  59 The type of a message iterator is #bt_message_iterator.
  60
  61 There are two contexts from which you can create a message iterator:
  62
  63 <dl>
  64   <dt>From another message iterator</dt>
  65   <dd>
  66     This is the case for a \bt_flt_comp's message iterator.
  67
  68     Use bt_message_iterator_create_from_message_iterator().
  69
  70     You can call this function from any message iterator
  71     \ref api-msg-iter-cls-methods "method" except the
  72     \ref api-msg-iter-cls-meth-fini "finalization method".
  73   </dd>
  74
  75   <dt>From a \bt_sink_comp</dt>
  76   <dd>
  77     Use bt_message_iterator_create_from_sink_component().
  78
  79     You can call this function from a sink component
  80     \ref api-comp-cls-dev-methods "method" once the trace processing
  81     graph which contains the component is
  82     \ref api-graph-lc "configured", that is:
  83
  84     - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured"
  85       method (typical).
  86
  87     - \ref api-comp-cls-dev-meth-consume "Consume" method.
  88   </dd>
  89 </dl>
  90
  91 When you call one of the creation functions above, you pass an \bt_iport
  92 on which to create the message iterator.
  93
  94 You can create more than one message iterator on a given
  95 <em>\ref api-port-prop-is-connected "connected"</em> input port. The
  96 \bt_p_conn between \bt_p_port in a trace processing \bt_graph establish
  97 which \bt_p_comp and message iterators can create message iterators of
  98 other \bt_p_comp. Then:
  99
 100 - Any \bt_sink_comp is free to create one or more message iterators
 101   on any of its connected input ports.
 102
 103 - Any message iterator is free to create one or more message iterators
 104   on any of its component's connected input ports.
 105
 106 The following illustration shows a very simple use case where the
 107 \ref api-comp-cls-dev-meth-consume "consuming method" of a sink
 108 component uses a single \bt_flt_comp's message iterator which itself
 109 uses a single \bt_src_comp's message iterator:
 110
 111 @image html msg-iter.png
 112
 113 Many message iterator relations are possible, for example:
 114
 115 @image html msg-iter-complex.png
 116
 117 <h1>\anchor api-msg-iter-ops Operations</h1>
 118
 119 Once you have created a message iterator, there are three possible
 120 operations:
 121
 122 <dl>
 123   <dt>
 124     \anchor api-msg-iter-op-next
 125     Get the message iterator's next messages
 126   </dt>
 127   <dd>
 128     This operation returns a batch of the message iterator's next
 129     \bt_p_msg considering its current state.
 130
 131     This operation returns a batch of messages instead of a single
 132     message for performance reasons.
 133
 134     This operation is said to \em advance the message iterator.
 135
 136     Get the next messages of a message iterator with
 137     bt_message_iterator_next().
 138   </dd>
 139
 140   <dt>
 141     \anchor api-msg-iter-op-seek-beg
 142     Make the message iterator seek its beginning
 143   </dt>
 144   <dd>
 145     This operation resets the message iterator's position to the
 146     beginning of its \ref api-msg-seq "message sequence".
 147
 148     If the operation is successful, then the next call to
 149     bt_message_iterator_next() returns the first \bt_p_msg of the
 150     message iterator's sequence.
 151
 152     If bt_message_iterator_seek_ns_from_origin() returns something
 153     else than #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK, you
 154     \em cannot call bt_message_iterator_next() afterwards. In that case,
 155     you can only call bt_message_iterator_seek_beginning() again or
 156     bt_message_iterator_seek_ns_from_origin().
 157
 158     Before you call bt_message_iterator_seek_beginning() to make
 159     the message iterator seek its beginning, check if it can currently
 160     do it with bt_message_iterator_can_seek_beginning().
 161   </dd>
 162
 163   <dt>
 164     \anchor api-msg-iter-op-seek-ns
 165     Make the message iterator seek a message occuring at or after a
 166     given time (in nanoseconds) from its clock class origin
 167   </dt>
 168   <dd>
 169     This operation changes the position of the message iterator within
 170     its \ref api-msg-seq "sequence" so that the next call to
 171     bt_message_iterator_next() returns \bt_p_msg which occur at or after
 172     a given time (in nanoseconds) from its
 173     \ref api-tir-clock-cls-origin "clock class origin".
 174
 175     When you call bt_message_iterator_seek_ns_from_origin() to perform
 176     the operation, your pass the specific time to seek as the
 177     \bt_p{ns_from_origin} parameter. You don't pass any
 178     \bt_clock_cls: the function operates at the nanosecond from some
 179     origin level and it is left to the message iterator's implementation
 180     to seek a message having at least this time.
 181
 182     If the requested time point is \em after the message iterator's
 183     sequence's last message, then the next call to
 184     bt_message_iterator_next() returns
 185     #BT_MESSAGE_ITERATOR_NEXT_STATUS_END.
 186
 187     If bt_message_iterator_seek_ns_from_origin() returns something
 188     else than #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK, you
 189     \em cannot call bt_message_iterator_next() afterwards. In that case,
 190     you can only call bt_message_iterator_seek_ns_from_origin() again
 191     or bt_message_iterator_seek_beginning().
 192
 193     Before you call bt_message_iterator_seek_ns_from_origin() to make
 194     the message iterator seek a specific point in time, check if it can
 195     currently do it with bt_message_iterator_can_seek_ns_from_origin().
 196   </dd>
 197 </dl>
 198 */
 199
 200 /*! @{ */
 201
 202 /*!
 203 @name Type
 204 @{
 205
 206 @typedef struct bt_message_iterator bt_message_iterator;
 207
 208 @brief
 209     Message iterator.
 210
 211 @}
 212 */
 213
 214 /*!
 215 @name Creation
 216 @{
 217 */
 218
 219 /*!
 220 @brief
 221     Status code for bt_message_iterator_create_from_message_iterator().
 222 */
 223 typedef enum bt_message_iterator_create_from_message_iterator_status {
 224         /*!
 225         @brief
 226             Success.
 227         */
 228         BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK              = __BT_FUNC_STATUS_OK,
 229
 230         /*!
 231         @brief
 232             Out of memory.
 233         */
 234         BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 235
 236         /*!
 237         @brief
 238             Other error.
 239         */
 240         BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
 241 } bt_message_iterator_create_from_message_iterator_status;
 242
 243 /*!
 244 @brief
 245     Creates a message iterator on the \bt_iport \bt_p{port} from
 246     another message iterator \bt_p{self_message_iterator}, and sets
 247     \bt_p{*message_iterator} to the resulting message iterator.
 248
 249 On success, the message iterator's position is at the beginning
 250 of its \ref api-msg-seq "message sequence".
 251
 252 @param[in] self_message_iterator
 253     Other message iterator from which to create the message iterator.
 254 @param[in] port
 255     Input port on which to create the message iterator.
 256 @param[out] message_iterator
 257     <strong>On success</strong>, \bt_p{*message_iterator} is a new
 258     message iterator reference.
 259
 260 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
 261     Success.
 262 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
 263     Out of memory.
 264 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
 265     Other error, for example, the created message iterator's
 266     \ref api-msg-iter-cls-meth-init "initialization method" failed.
 267
 268 @bt_pre_not_null{self_message_iterator}
 269 @bt_pre_not_null{port}
 270 @pre
 271     <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
 272 @bt_pre_not_null{message_iterator}
 273
 274 @sa bt_message_iterator_create_from_sink_component() &mdash;
 275     Creates a message iterator from a \bt_sink_comp.
 276 */
 277 extern bt_message_iterator_create_from_message_iterator_status
 278 bt_message_iterator_create_from_message_iterator(
 279                 bt_self_message_iterator *self_message_iterator,
 280                 bt_self_component_port_input *port,
 281                 bt_message_iterator **message_iterator);
 282
 283 /*!
 284 @brief
 285     Status code for bt_message_iterator_create_from_sink_component().
 286 */
 287 typedef enum bt_message_iterator_create_from_sink_component_status {
 288         /*!
 289         @brief
 290             Success.
 291         */
 292         BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK                = __BT_FUNC_STATUS_OK,
 293
 294         /*!
 295         @brief
 296             Out of memory.
 297         */
 298         BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 299
 300         /*!
 301         @brief
 302             Other error.
 303         */
 304         BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 305 } bt_message_iterator_create_from_sink_component_status;
 306
 307 /*!
 308 @brief
 309     Creates a message iterator on the \bt_iport \bt_p{port} from the
 310     \bt_sink_comp \bt_p{self_component_sink}, and sets
 311     \bt_p{*message_iterator} to the resulting message iterator.
 312
 313 On success, the message iterator's position is at the beginning
 314 of its \ref api-msg-seq "message sequence".
 315
 316 @param[in] self_component_sink
 317     Sink component from which to create the message iterator.
 318 @param[in] port
 319     Input port on which to create the message iterator.
 320 @param[out] message_iterator
 321     <strong>On success</strong>, \bt_p{*message_iterator} is a new
 322     message iterator reference.
 323
 324 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
 325     Success.
 326 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
 327     Out of memory.
 328 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
 329     Other error, for example, the created message iterator's
 330     \ref api-msg-iter-cls-meth-init "initialization method" failed.
 331
 332 @bt_pre_not_null{self_component_sink}
 333 @bt_pre_not_null{port}
 334 @pre
 335     <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
 336 @bt_pre_not_null{message_iterator}
 337
 338 @sa bt_message_iterator_create_from_message_iterator() &mdash;
 339     Creates a message iterator from another message iterator.
 340 */
 341 extern bt_message_iterator_create_from_sink_component_status
 342 bt_message_iterator_create_from_sink_component(
 343                 bt_self_component_sink *self_component_sink,
 344                 bt_self_component_port_input *port,
 345                 bt_message_iterator **message_iterator);
 346
 347 /*! @} */
 348
 349 /*!
 350 @name Component access
 351 @{
 352 */
 353
 354 /*!
 355 @brief
 356     Borrows the \bt_comp which provides the \bt_msg_iter
 357     \bt_p{message_iterator}.
 358
 359 @param[in] message_iterator
 360     Message iterator from which to borrow the component which provides
 361     it.
 362
 363 @returns
 364     Component which provides \bt_p{message_iterator}.
 365
 366 @bt_pre_not_null{message_iterator}
 367 */
 368 extern bt_component *
 369 bt_message_iterator_borrow_component(
 370                 bt_message_iterator *message_iterator);
 371
 372 /*! @} */
 373
 374 /*!
 375 @name "Next" operation (get next messages)
 376 @{
 377 */
 378
 379 /*!
 380 @brief
 381     Status code for bt_message_iterator_next().
 382 */
 383 typedef enum bt_message_iterator_next_status {
 384         /*!
 385         @brief
 386             Success.
 387         */
 388         BT_MESSAGE_ITERATOR_NEXT_STATUS_OK              = __BT_FUNC_STATUS_OK,
 389
 390         /*!
 391         @brief
 392             End of iteration.
 393         */
 394         BT_MESSAGE_ITERATOR_NEXT_STATUS_END             = __BT_FUNC_STATUS_END,
 395
 396         /*!
 397         @brief
 398             Try again.
 399         */
 400         BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN           = __BT_FUNC_STATUS_AGAIN,
 401
 402         /*!
 403         @brief
 404             Out of memory.
 405         */
 406         BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 407
 408         /*!
 409         @brief
 410             Other error.
 411         */
 412         BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
 413 } bt_message_iterator_next_status;
 414
 415 /*!
 416 @brief
 417     Returns the next \bt_p_msg of the message iterator
 418     \bt_p{message_iterator} into the \bt_p{*messages} array of size
 419     \bt_p{*count}, effectively advancing \bt_p{message_iterator}.
 420
 421 See \ref api-msg-iter-op-next "this operation's documentation".
 422
 423 On success, the message iterator's position is advanced by \bt_p{*count}
 424 messages.
 425
 426 @param[in] message_iterator
 427     Message iterator from which to get the next messages.
 428 @param[out] messages
 429     @parblock
 430     <strong>On success</strong>, \bt_p{*messages} is an array containing
 431     the next messages of \bt_p{message_iterator} as its first elements.
 432
 433     \bt_p{*count} is the number of messages in \bt_p{*messages}.
 434
 435     The library allocates and manages this array, but until you
 436     perform another \ref api-msg-iter-ops "operation" on
 437     \bt_p{message_iterator}, you are free to modify it. For example,
 438     you can set its elements to \c NULL if your use case needs it.
 439
 440     You own the references of the messages this array contains. In
 441     other words, you must put them with bt_message_put_ref() or move
 442     them to another message array (from a
 443     \link api-msg-iter-cls-meth-next "next" method\endlink)
 444     before you perform another operation on \bt_p{message_iterator} or
 445     before \bt_p{message_iterator} is destroyed.
 446     @endparblock
 447 @param[out] count
 448     <strong>On success</strong>, \bt_p{*count} is the number of messages
 449     in \bt_p{*messages}.
 450
 451 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
 452     Success.
 453 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
 454     End of iteration.
 455 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
 456     Try again.
 457 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
 458     Out of memory.
 459 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
 460     Other error.
 461
 462 @bt_pre_not_null{message_iterator}
 463 @bt_pre_not_null{messages}
 464 @bt_pre_not_null{count}
 465
 466 @post
 467     <strong>On success</strong>, \bt_p{*count}&nbsp;≥&nbsp;1.
 468 */
 469 extern bt_message_iterator_next_status
 470 bt_message_iterator_next(bt_message_iterator *message_iterator,
 471                 bt_message_array_const *messages, uint64_t *count);
 472
 473 /*! @} */
 474
 475 /*!
 476 @name Seeking
 477 @{
 478 */
 479
 480 /*!
 481 @brief
 482     Status code for bt_message_iterator_can_seek_beginning().
 483 */
 484 typedef enum bt_message_iterator_can_seek_beginning_status {
 485         /*!
 486         @brief
 487             Success.
 488         */
 489         BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK                = __BT_FUNC_STATUS_OK,
 490
 491         /*!
 492         @brief
 493             Try again.
 494         */
 495         BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN             = __BT_FUNC_STATUS_AGAIN,
 496
 497         /*!
 498         @brief
 499             Out of memory.
 500         */
 501         BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 502
 503         /*!
 504         @brief
 505             Other error.
 506         */
 507         BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 508 } bt_message_iterator_can_seek_beginning_status;
 509
 510 /*!
 511 @brief
 512     Returns whether or not the message iterator \bt_p{message_iterator}
 513     can currently seek its beginning (first \bt_msg).
 514
 515 See the \link api-msg-iter-op-seek-beg "seek beginning"
 516 operation\endlink.
 517
 518 Make sure to call this function, without performing any other
 519 \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
 520 call bt_message_iterator_seek_beginning().
 521
 522 @param[in] message_iterator
 523     Message iterator from which to to get whether or not it can seek
 524     its beginning.
 525 @param[out] can_seek_beginning
 526     <strong>On success</strong>, \bt_p{*can_seek_beginning} is #BT_TRUE
 527     if \bt_p{message_iterator} can seek its beginning.
 528
 529 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
 530     Success.
 531 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
 532     Try again.
 533 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
 534     Out of memory.
 535 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
 536     Other error.
 537
 538 @bt_pre_not_null{message_iterator}
 539 @bt_pre_not_null{can_seek_beginning}
 540
 541 @sa bt_message_iterator_seek_beginning() &mdash;
 542     Makes a message iterator seek its beginning.
 543 */
 544 extern bt_message_iterator_can_seek_beginning_status
 545 bt_message_iterator_can_seek_beginning(
 546                 bt_message_iterator *message_iterator,
 547                 bt_bool *can_seek_beginning);
 548
 549 /*!
 550 @brief
 551     Status code for bt_message_iterator_seek_beginning().
 552 */
 553 typedef enum bt_message_iterator_seek_beginning_status {
 554         /*!
 555         @brief
 556             Success.
 557         */
 558         BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK            = __BT_FUNC_STATUS_OK,
 559
 560         /*!
 561         @brief
 562             Try again.
 563         */
 564         BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN         = __BT_FUNC_STATUS_AGAIN,
 565
 566         /*!
 567         @brief
 568             Out of memory.
 569         */
 570         BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 571
 572         /*!
 573         @brief
 574             Other error.
 575         */
 576         BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
 577 } bt_message_iterator_seek_beginning_status;
 578
 579 /*!
 580 @brief
 581     Makes the message iterator \bt_p{message_iterator} seek its
 582     beginning (first \bt_msg).
 583
 584 See \ref api-msg-iter-op-seek-beg "this operation's documentation".
 585
 586 Make sure to call bt_message_iterator_can_seek_beginning(),
 587 without performing any other \ref api-msg-iter-ops "operation" on
 588 \bt_p{message_iterator}, before you call this function.
 589
 590 @param[in] message_iterator
 591     Message iterator to seek to its beginning.
 592
 593 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
 594     Success.
 595 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
 596     Try again.
 597 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
 598     Out of memory.
 599 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
 600     Other error.
 601
 602 @bt_pre_not_null{message_iterator}
 603 @pre
 604     <code>bt_message_iterator_can_seek_beginning(message_iterator)</code>
 605     returns #BT_TRUE.
 606
 607 @sa bt_message_iterator_can_seek_beginning() &mdash;
 608     Returns whether or not a message iterator can currently seek its
 609     beginning.
 610 */
 611 extern bt_message_iterator_seek_beginning_status
 612 bt_message_iterator_seek_beginning(
 613                 bt_message_iterator *message_iterator);
 614
 615 /*!
 616 @brief
 617     Status code for bt_message_iterator_can_seek_ns_from_origin().
 618 */
 619 typedef enum bt_message_iterator_can_seek_ns_from_origin_status {
 620         /*!
 621         @brief
 622             Success.
 623         */
 624         BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK           = __BT_FUNC_STATUS_OK,
 625
 626         /*!
 627         @brief
 628             Try again.
 629         */
 630         BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN        = __BT_FUNC_STATUS_AGAIN,
 631
 632         /*!
 633         @brief
 634             Out of memory.
 635         */
 636         BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 637
 638         /*!
 639         @brief
 640             Other error.
 641         */
 642         BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
 643 } bt_message_iterator_can_seek_ns_from_origin_status;
 644
 645 /*!
 646 @brief
 647     Returns whether or not the message iterator \bt_p{message_iterator}
 648     can currently seek a \bt_msg occuring at or after
 649     \bt_p{ns_from_origin} nanoseconds from its
 650     \ref api-tir-clock-cls-origin "clock class origin".
 651
 652 See the \link api-msg-iter-op-seek-ns "seek ns from origin"
 653 operation\endlink.
 654
 655 Make sure to call this function, without performing any other
 656 \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
 657 call bt_message_iterator_seek_ns_from_origin().
 658
 659 @param[in] message_iterator
 660     Message iterator from which to to get whether or not it can seek
 661     its beginning.
 662 @param[in] ns_from_origin
 663     Requested time point to seek.
 664 @param[out] can_seek_ns_from_origin
 665     <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is
 666     #BT_TRUE if \bt_p{message_iterator} can seek a message occuring at
 667     or after \bt_p{ns_from_origin} nanoseconds from its clock class
 668     origin.
 669
 670 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
 671     Success.
 672 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
 673     Try again.
 674 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
 675     Out of memory.
 676 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
 677     Other error.
 678
 679 @bt_pre_not_null{message_iterator}
 680 @bt_pre_not_null{can_seek_ns_from_origin}
 681
 682 @sa bt_message_iterator_seek_ns_from_origin() &mdash;
 683     Makes a message iterator seek a message occuring at or after
 684     a given time from its clock class origin.
 685 */
 686
 687 extern bt_message_iterator_can_seek_ns_from_origin_status
 688 bt_message_iterator_can_seek_ns_from_origin(
 689                 bt_message_iterator *message_iterator,
 690                 int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
 691
 692 /*!
 693 @brief
 694     Status code for bt_message_iterator_seek_ns_from_origin().
 695 */
 696 typedef enum bt_message_iterator_seek_ns_from_origin_status {
 697         /*!
 698         @brief
 699             Success.
 700         */
 701         BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
 702
 703         /*!
 704         @brief
 705             Try again.
 706         */
 707         BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
 708
 709         /*!
 710         @brief
 711             Out of memory.
 712         */
 713         BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 714
 715         /*!
 716         @brief
 717             Other error.
 718         */
 719         BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 720 } bt_message_iterator_seek_ns_from_origin_status;
 721
 722 /*!
 723 @brief
 724     Makes the message iterator \bt_p{message_iterator} seek a \bt_msg
 725     occuring at or after \bt_p{ns_from_origin} nanoseconds from its
 726     \ref api-tir-clock-cls-origin "clock class origin".
 727
 728 See \ref api-msg-iter-op-seek-ns "this operation's documentation".
 729
 730 Make sure to call bt_message_iterator_can_seek_ns_from_origin(),
 731 without performing any other \ref api-msg-iter-ops "operation" on
 732 \bt_p{message_iterator}, before you call this function.
 733
 734 @param[in] message_iterator
 735     Message iterator to seek to a message occuring at or after
 736     \bt_p{ns_from_origin} nanoseconds from its clock class origin.
 737 @param[in] ns_from_origin
 738     Time point to seek.
 739
 740 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
 741     Success.
 742 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
 743     Try again.
 744 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
 745     Out of memory.
 746 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
 747     Other error.
 748
 749 @bt_pre_not_null{message_iterator}
 750 @pre
 751     <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator,&nbsp;ns_from_origin)</code>
 752     returns #BT_TRUE.
 753
 754 @sa bt_message_iterator_can_seek_ns_from_origin() &mdash;
 755     Returns whether or not a message iterator can currently seek a
 756     message occuring at or after a given time from its clock class
 757     origin.
 758 */
 759 extern bt_message_iterator_seek_ns_from_origin_status
 760 bt_message_iterator_seek_ns_from_origin(
 761                 bt_message_iterator *message_iterator,
 762                 int64_t ns_from_origin);
 763
 764 /*! @} */
 765
 766 /*!
 767 @name Configuration
 768 @{
 769 */
 770
 771 /*!
 772 @brief
 773     Returns whether or not the message iterator \bt_p{message_iterator}
 774     can seek forward.
 775
 776 A message iterator can seek forward if all the \bt_p_msg of its
 777 message sequence have some \bt_cs.
 778
 779 @param[in] message_iterator
 780     Message iterator of which to get whether or not it can seek forward.
 781
 782 @returns
 783     #BT_TRUE if \bt_p{message_iterator} can seek forward.
 784
 785 @sa bt_self_message_iterator_configuration_set_can_seek_forward() &mdash;
 786     Sets whether or not a message iterator can seek forward.
 787 */
 788 extern bt_bool
 789 bt_message_iterator_can_seek_forward(
 790                 bt_message_iterator *message_iterator);
 791
 792 /*! @} */
 793
 794 /*!
 795 @name Reference count
 796 @{
 797 */
 798
 799 /*!
 800 @brief
 801     Increments the \ref api-fund-shared-object "reference count" of
 802     the message iterator \bt_p{message_iterator}.
 803
 804 @param[in] message_iterator
 805     @parblock
 806     Message iterator of which to increment the reference count.
 807
 808     Can be \c NULL.
 809     @endparblock
 810
 811 @sa bt_message_iterator_put_ref() &mdash;
 812     Decrements the reference count of a message iterator.
 813 */
 814 extern void bt_message_iterator_get_ref(
 815                 const bt_message_iterator *message_iterator);
 816
 817 /*!
 818 @brief
 819     Decrements the \ref api-fund-shared-object "reference count" of
 820     the message iterator \bt_p{message_iterator}.
 821
 822 @param[in] message_iterator
 823     @parblock
 824     Message iterator of which to decrement the reference count.
 825
 826     Can be \c NULL.
 827     @endparblock
 828
 829 @sa bt_message_iterator_get_ref() &mdash;
 830     Increments the reference count of a message iterator.
 831 */
 832 extern void bt_message_iterator_put_ref(
 833                 const bt_message_iterator *message_iterator);
 834
 835 /*!
 836 @brief
 837     Decrements the reference count of the message iterator
 838     \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
 839     to \c NULL.
 840
 841 @param _message_iterator
 842     @parblock
 843     Message iterator of which to decrement the reference count.
 844
 845     Can contain \c NULL.
 846     @endparblock
 847
 848 @bt_pre_assign_expr{_message_iterator}
 849 */
 850 #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator)        \
 851         do {                                                            \
 852                 bt_message_iterator_put_ref(_message_iterator);         \
 853                 (_message_iterator) = NULL;                             \
 854         } while (0)
 855
 856 /*!
 857 @brief
 858     Decrements the reference count of the message iterator \bt_p{_dst},
 859     sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
 860     \c NULL.
 861
 862 This macro effectively moves a message iterator reference from the
 863 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 864 existing \bt_p{_dst} reference.
 865
 866 @param _dst
 867     @parblock
 868     Destination expression.
 869
 870     Can contain \c NULL.
 871     @endparblock
 872 @param _src
 873     @parblock
 874     Source expression.
 875
 876     Can contain \c NULL.
 877     @endparblock
 878
 879 @bt_pre_assign_expr{_dst}
 880 @bt_pre_assign_expr{_src}
 881 */
 882 #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src)        \
 883         do {                                            \
 884                 bt_message_iterator_put_ref(_dst);      \
 885                 (_dst) = (_src);                        \
 886                 (_src) = NULL;                          \
 887         } while (0)
 888
 889 /*! @} */
 890
 891 /*! @} */
 892
 893 #ifdef __cplusplus
 894 }
 895 #endif
 896
 897 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */