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