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