include/babeltrace2/trace-ir/stream.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_TRACE_IR_STREAM_H
   8 #define BABELTRACE2_TRACE_IR_STREAM_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 #include <stdint.h>
  17
  18 #include <babeltrace2/types.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25 @defgroup api-tir-stream Stream
  26 @ingroup api-tir
  27
  28 @brief
  29     Trace stream.
  30
  31 A <strong><em>stream</em></strong> is a conceptual
  32 \ref api-msg-seq "sequence of messages" within a \bt_trace:
  33
  34 @image html trace-structure.png
  35
  36 In the illustration above, notice that:
  37
  38 - A \bt_stream is a conceptual sequence of \bt_p_msg.
  39
  40   The sequence always starts with a \bt_sb_msg and ends with a
  41   \bt_se_msg.
  42
  43 - A stream is an instance of a \bt_stream_cls.
  44
  45 - A \bt_trace contains one or more streams.
  46
  47 A stream is a \ref api-tir "trace IR" data object.
  48
  49 A stream is said to be a \em conceptual sequence of messages because the
  50 stream object itself does not contain messages: it only represents a
  51 common timeline to which messages are associated.
  52
  53 \bt_cp_comp exchange messages, within a trace processing \bt_graph,
  54 which can belong to different streams, as long as the stream clocks are
  55 \ref api-tir-clock-cls-origin "correlatable".
  56
  57 A typical use case for streams is to use one for each traced CPU. Then
  58 the messages related to a given stream are the ones which occurred on a
  59 given CPU. Other schemes are possible: they are completely
  60 application-specific, and \bt_name does not enforce any specific
  61 stream arrangement pattern.
  62
  63 A \bt_trace contains streams. All the streams of a
  64 given trace, for a given stream class, have unique numeric IDs. Borrow
  65 the trace which contains a stream with bt_stream_borrow_trace() or
  66 bt_stream_borrow_trace_const().
  67
  68 A \bt_stream can conceptually contain a default clock if its class
  69 has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
  70 There's no function to access a stream's default clock because it's
  71 a stateful object: \bt_p_msg cannot refer to stateful objects
  72 because they must not change while being transported from one
  73 \bt_comp to the other. Instead of having a stream default clock object,
  74 \bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
  75 stream's default clock (a \bt_clock_cls instance):
  76
  77 @image html clocks.png
  78
  79 In the illustration above, notice that:
  80
  81 - Streams (horizontal blue rectangles) are instances of a
  82   \bt_stream_cls (orange).
  83
  84 - A stream class has a default \bt_clock_cls (orange bell alarm clock).
  85
  86 - Each stream has a default clock (yellow bell alarm clock): this is an
  87   instance of the stream's class's default clock class.
  88
  89 - Each \bt_msg (objects in blue stream rectangles) created for a given
  90   stream has a default \bt_cs (yellow star): this is a snapshot of the
  91   stream's default clock.
  92
  93   In other words, a default clock snapshot contains the value of the
  94   stream's default clock when this message occurred.
  95
  96 To create a stream:
  97
  98 <dl>
  99   <dt>
 100     If bt_stream_class_assigns_automatic_stream_id() returns
 101     #BT_TRUE (the default) for the stream class to use
 102   </dt>
 103   <dd>Use bt_stream_create().</dd>
 104
 105   <dt>
 106     If bt_stream_class_assigns_automatic_stream_id() returns
 107     #BT_FALSE for the stream class to use
 108   </dt>
 109   <dd>Use bt_stream_create_with_id().</dd>
 110 </dl>
 111
 112 A stream is a \ref api-fund-shared-object "shared object": get a
 113 new reference with bt_stream_get_ref() and put an existing
 114 reference with bt_stream_put_ref().
 115
 116 Some library functions \ref api-fund-freezing "freeze" streams on
 117 success. The documentation of those functions indicate this
 118 postcondition.
 119
 120 The type of a stream is #bt_stream.
 121
 122 <h1>Properties</h1>
 123
 124 A stream has the following property:
 125
 126 <dl>
 127   <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
 128   <dd>
 129     Numeric ID, unique amongst the numeric IDs of the stream's
 130     \bt_trace's streams for a given \bt_stream_cls. In other words,
 131     two streams which belong to the same trace can have the same numeric
 132     ID if they aren't instances of the same class.
 133
 134     Depending on whether or not the stream's class
 135     automatically assigns stream IDs
 136     (see bt_stream_class_assigns_automatic_stream_id()),
 137     set the stream's numeric ID on creation with
 138     bt_stream_create() or bt_stream_create_with_id().
 139
 140     You cannot change the numeric ID once the stream is created.
 141
 142     Get a stream's numeric ID with bt_stream_get_id().
 143   </dd>
 144
 145   <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
 146   <dd>
 147     Name of the stream.
 148
 149     Use bt_stream_set_name() and bt_stream_get_name().
 150   </dd>
 151
 152   <dt>
 153     \anchor api-tir-stream-prop-user-attrs
 154     \bt_dt_opt User attributes
 155   </dt>
 156   <dd>
 157     User attributes of the stream.
 158
 159     User attributes are custom attributes attached to a stream.
 160
 161     Use bt_stream_set_user_attributes(),
 162     bt_stream_borrow_user_attributes(), and
 163     bt_stream_borrow_user_attributes_const().
 164   </dd>
 165 </dl>
 166 */
 167
 168 /*! @{ */
 169
 170 /*!
 171 @name Type
 172 @{
 173
 174 @typedef struct bt_stream bt_stream;
 175
 176 @brief
 177     Stream.
 178
 179 @}
 180 */
 181
 182 /*!
 183 @name Creation
 184 @{
 185 */
 186
 187 /*!
 188 @brief
 189     Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
 190     adds it to the \bt_trace \bt_p{trace}.
 191
 192 This function instantiates \bt_p{stream_class}.
 193
 194 @attention
 195     @parblock
 196     Only use this function if
 197
 198     @code
 199     bt_stream_class_assigns_automatic_stream_id(stream_class)
 200     @endcode
 201
 202     returns #BT_TRUE.
 203
 204     Otherwise, use bt_stream_create_with_id().
 205     @endparblock
 206
 207 On success, the returned stream has the following property values:
 208
 209 <table>
 210   <tr>
 211     <th>Property
 212     <th>Value
 213   <tr>
 214     <td>\ref api-tir-stream-prop-id "Numeric ID"
 215     <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
 216   <tr>
 217     <td>\ref api-tir-stream-prop-name "Name"
 218     <td>\em None
 219   <tr>
 220     <td>\ref api-tir-stream-prop-user-attrs "User attributes"
 221     <td>Empty \bt_map_val
 222 </table>
 223
 224 @param[in] stream_class
 225     Stream class from which to create the stream.
 226 @param[in] trace
 227     Trace to add the created stream to.
 228
 229 @returns
 230     New stream reference, or \c NULL on memory error.
 231
 232 @bt_pre_not_null{stream_class}
 233 @pre
 234     <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
 235     returns #BT_TRUE.
 236 @bt_pre_not_null{trace}
 237
 238 @bt_post_success_frozen{stream_class}
 239 @bt_post_success_frozen{trace}
 240
 241 @sa bt_stream_create_with_id() &mdash;
 242     Creates a stream with a specific numeric ID and adds it to a
 243     trace.
 244 */
 245 extern bt_stream *bt_stream_create(bt_stream_class *stream_class,
 246                 bt_trace *trace) __BT_NOEXCEPT;
 247
 248 /*!
 249 @brief
 250     Creates a stream with the numeric ID \bt_p{id}
 251     from the \bt_stream_cls \bt_p{stream_class} and adds
 252     it to the \bt_trace \bt_p{trace}.
 253
 254 This function instantiates \bt_p{stream_class}.
 255
 256 @attention
 257     @parblock
 258     Only use this function if
 259
 260     @code
 261     bt_stream_class_assigns_automatic_stream_id(stream_class)
 262     @endcode
 263
 264     returns #BT_FALSE.
 265
 266     Otherwise, use bt_stream_create().
 267     @endparblock
 268
 269 On success, the returned stream has the following property values:
 270
 271 <table>
 272   <tr>
 273     <th>Property
 274     <th>Value
 275   <tr>
 276     <td>\ref api-tir-stream-prop-id "Numeric ID"
 277     <td>\bt_p{id}
 278   <tr>
 279     <td>\ref api-tir-stream-prop-name "Name"
 280     <td>\em None
 281   <tr>
 282     <td>\ref api-tir-stream-prop-user-attrs "User attributes"
 283     <td>Empty \bt_map_val
 284 </table>
 285
 286 @param[in] stream_class
 287     Stream class from which to create the stream.
 288 @param[in] trace
 289     Trace to add the created stream to.
 290 @param[in] id
 291     Numeric ID of the stream to create and add to \bt_p{trace}.
 292
 293 @returns
 294     New stream reference, or \c NULL on memory error.
 295
 296 @bt_pre_not_null{stream_class}
 297 @pre
 298     <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
 299     returns #BT_FALSE.
 300 @bt_pre_not_null{trace}
 301 @pre
 302     \bt_p{trace} does not contain an instance of \bt_p{stream_class}
 303     with the numeric ID \bt_p{id}.
 304
 305 @bt_post_success_frozen{stream_class}
 306 @bt_post_success_frozen{trace}
 307
 308 @sa bt_stream_create() &mdash;
 309     Creates a stream with an automatic numeric ID and adds it to a
 310     trace.
 311 */
 312 extern bt_stream *bt_stream_create_with_id(
 313                 bt_stream_class *stream_class,
 314                 bt_trace *trace, uint64_t id) __BT_NOEXCEPT;
 315
 316 /*! @} */
 317
 318 /*!
 319 @name Class access
 320 @{
 321 */
 322
 323 /*!
 324 @brief
 325     Borrows the \ref api-tir-stream-cls "class" of the stream
 326     \bt_p{stream}.
 327
 328 @param[in] stream
 329     Stream of which to borrow the class.
 330
 331 @returns
 332     \em Borrowed reference of the class of \bt_p{stream}.
 333
 334 @bt_pre_not_null{stream}
 335
 336 @sa bt_stream_borrow_class_const() &mdash;
 337     \c const version of this function.
 338 */
 339 extern bt_stream_class *bt_stream_borrow_class(bt_stream *stream) __BT_NOEXCEPT;
 340
 341 /*!
 342 @brief
 343     Borrows the \ref api-tir-stream-cls "class" of the stream
 344     \bt_p{stream} (\c const version).
 345
 346 See bt_stream_borrow_class().
 347 */
 348 extern const bt_stream_class *bt_stream_borrow_class_const(
 349                 const bt_stream *stream) __BT_NOEXCEPT;
 350
 351 /*! @} */
 352
 353 /*!
 354 @name Trace access
 355 @{
 356 */
 357
 358 /*!
 359 @brief
 360     Borrows the \bt_trace which contains the stream \bt_p{stream}.
 361
 362 @param[in] stream
 363     Stream of which to borrow the trace containing it.
 364
 365 @returns
 366     \em Borrowed reference of the trace containing \bt_p{stream}.
 367
 368 @bt_pre_not_null{stream}
 369
 370 @sa bt_stream_borrow_trace_const() &mdash;
 371     \c const version of this function.
 372 */
 373 extern bt_trace *bt_stream_borrow_trace(bt_stream *stream) __BT_NOEXCEPT;
 374
 375 /*!
 376 @brief
 377     Borrows the \bt_trace which contains the stream \bt_p{stream}
 378     (\c const version).
 379
 380 See bt_stream_borrow_trace().
 381 */
 382 extern const bt_trace *bt_stream_borrow_trace_const(
 383                 const bt_stream *stream) __BT_NOEXCEPT;
 384
 385 /*! @} */
 386
 387 /*!
 388 @name Properties
 389 @{
 390 */
 391
 392 /*!
 393 @brief
 394     Returns the numeric ID of the stream \bt_p{stream}.
 395
 396 See the \ref api-tir-stream-prop-id "numeric ID" property.
 397
 398 @param[in] stream
 399     Stream of which to get the numeric ID.
 400
 401 @returns
 402     Numeric ID of \bt_p{stream}.
 403
 404 @bt_pre_not_null{stream}
 405
 406 @sa bt_stream_create_with_id() &mdash;
 407     Creates a stream with a specific numeric ID and adds it to a
 408     trace.
 409 */
 410 extern uint64_t bt_stream_get_id(const bt_stream *stream) __BT_NOEXCEPT;
 411
 412 /*!
 413 @brief
 414     Status codes for bt_stream_set_name().
 415 */
 416 typedef enum bt_stream_set_name_status {
 417         /*!
 418         @brief
 419             Success.
 420         */
 421         BT_STREAM_SET_NAME_STATUS_OK            = __BT_FUNC_STATUS_OK,
 422
 423         /*!
 424         @brief
 425             Out of memory.
 426         */
 427         BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 428 } bt_stream_set_name_status;
 429
 430 /*!
 431 @brief
 432     Sets the name of the stream \bt_p{stream} to
 433     a copy of \bt_p{name}.
 434
 435 See the \ref api-tir-stream-prop-name "name" property.
 436
 437 @param[in] stream
 438     Stream of which to set the name to \bt_p{name}.
 439 @param[in] name
 440     New name of \bt_p{stream} (copied).
 441
 442 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
 443     Success.
 444 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 445     Out of memory.
 446
 447 @bt_pre_not_null{stream}
 448 @bt_pre_hot{stream}
 449 @bt_pre_not_null{name}
 450
 451 @sa bt_stream_get_name() &mdash;
 452     Returns the name of a stream.
 453 */
 454 extern bt_stream_set_name_status bt_stream_set_name(bt_stream *stream,
 455                 const char *name) __BT_NOEXCEPT;
 456
 457 /*!
 458 @brief
 459     Returns the name of the stream \bt_p{stream}.
 460
 461 See the \ref api-tir-stream-prop-name "name" property.
 462
 463 If \bt_p{stream} has no name, this function returns \c NULL.
 464
 465 @param[in] stream
 466     Stream of which to get the name.
 467
 468 @returns
 469     @parblock
 470     Name of \bt_p{stream}, or \c NULL if none.
 471
 472     The returned pointer remains valid as long as \bt_p{stream}
 473     is not modified.
 474     @endparblock
 475
 476 @bt_pre_not_null{stream}
 477
 478 @sa bt_stream_class_set_name() &mdash;
 479     Sets the name of a stream.
 480 */
 481 extern const char *bt_stream_get_name(const bt_stream *stream) __BT_NOEXCEPT;
 482
 483 /*!
 484 @brief
 485     Sets the user attributes of the stream \bt_p{stream} to
 486     \bt_p{user_attributes}.
 487
 488 See the \ref api-tir-stream-prop-user-attrs "user attributes"
 489 property.
 490
 491 @note
 492     When you create a default stream with bt_stream_create()
 493     or bt_stream_create_with_id(), the stream's initial user
 494     attributes is an empty \bt_map_val. Therefore you can borrow it with
 495     bt_stream_borrow_user_attributes() and fill it directly
 496     instead of setting a new one with this function.
 497
 498 @param[in] stream
 499     Stream of which to set the user attributes to
 500     \bt_p{user_attributes}.
 501 @param[in] user_attributes
 502     New user attributes of \bt_p{stream}.
 503
 504 @bt_pre_not_null{stream}
 505 @bt_pre_hot{stream}
 506 @bt_pre_not_null{user_attributes}
 507 @bt_pre_is_map_val{user_attributes}
 508
 509 @sa bt_stream_borrow_user_attributes() &mdash;
 510     Borrows the user attributes of a stream.
 511 */
 512 extern void bt_stream_set_user_attributes(
 513                 bt_stream *stream, const bt_value *user_attributes)
 514                 __BT_NOEXCEPT;
 515
 516 /*!
 517 @brief
 518     Borrows the user attributes of the stream \bt_p{stream}.
 519
 520 See the \ref api-tir-stream-prop-user-attrs "user attributes"
 521 property.
 522
 523 @note
 524     When you create a default stream with bt_stream_create()
 525     or bt_stream_create_with_id(), the stream's initial user
 526     attributes is an empty \bt_map_val.
 527
 528 @param[in] stream
 529     Stream from which to borrow the user attributes.
 530
 531 @returns
 532     User attributes of \bt_p{stream} (a \bt_map_val).
 533
 534 @bt_pre_not_null{stream}
 535
 536 @sa bt_stream_set_user_attributes() &mdash;
 537     Sets the user attributes of a stream.
 538 @sa bt_stream_borrow_user_attributes_const() &mdash;
 539     \c const version of this function.
 540 */
 541 extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream)
 542                 __BT_NOEXCEPT;
 543
 544 /*!
 545 @brief
 546     Borrows the user attributes of the stream \bt_p{stream}
 547     (\c const version).
 548
 549 See bt_stream_borrow_user_attributes().
 550 */
 551 extern const bt_value *bt_stream_borrow_user_attributes_const(
 552                 const bt_stream *stream) __BT_NOEXCEPT;
 553
 554 /*! @} */
 555
 556 /*!
 557 @name Reference count
 558 @{
 559 */
 560
 561 /*!
 562 @brief
 563     Increments the \ref api-fund-shared-object "reference count" of
 564     the stream \bt_p{stream}.
 565
 566 @param[in] stream
 567     @parblock
 568     Stream of which to increment the reference count.
 569
 570     Can be \c NULL.
 571     @endparblock
 572
 573 @sa bt_stream_put_ref() &mdash;
 574     Decrements the reference count of a stream.
 575 */
 576 extern void bt_stream_get_ref(const bt_stream *stream) __BT_NOEXCEPT;
 577
 578 /*!
 579 @brief
 580     Decrements the \ref api-fund-shared-object "reference count" of
 581     the stream \bt_p{stream}.
 582
 583 @param[in] stream
 584     @parblock
 585     Stream of which to decrement the reference count.
 586
 587     Can be \c NULL.
 588     @endparblock
 589
 590 @sa bt_stream_get_ref() &mdash;
 591     Increments the reference count of a stream.
 592 */
 593 extern void bt_stream_put_ref(const bt_stream *stream) __BT_NOEXCEPT;
 594
 595 /*!
 596 @brief
 597     Decrements the reference count of the stream
 598     \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
 599
 600 @param _stream
 601     @parblock
 602     Stream of which to decrement the reference count.
 603
 604     Can contain \c NULL.
 605     @endparblock
 606
 607 @bt_pre_assign_expr{_stream}
 608 */
 609 #define BT_STREAM_PUT_REF_AND_RESET(_stream)            \
 610         do {                                            \
 611                 bt_stream_put_ref(_stream);             \
 612                 (_stream) = NULL;                       \
 613         } while (0)
 614
 615 /*!
 616 @brief
 617     Decrements the reference count of the stream \bt_p{_dst}, sets
 618     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 619
 620 This macro effectively moves a stream reference from the expression
 621 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 622 \bt_p{_dst} reference.
 623
 624 @param _dst
 625     @parblock
 626     Destination expression.
 627
 628     Can contain \c NULL.
 629     @endparblock
 630 @param _src
 631     @parblock
 632     Source expression.
 633
 634     Can contain \c NULL.
 635     @endparblock
 636
 637 @bt_pre_assign_expr{_dst}
 638 @bt_pre_assign_expr{_src}
 639 */
 640 #define BT_STREAM_MOVE_REF(_dst, _src)          \
 641         do {                                    \
 642                 bt_stream_put_ref(_dst);        \
 643                 (_dst) = (_src);                \
 644                 (_src) = NULL;                  \
 645         } while (0)
 646
 647 /*! @} */
 648
 649 /*! @} */
 650
 651 #ifdef __cplusplus
 652 }
 653 #endif
 654
 655 #endif /* BABELTRACE2_TRACE_IR_STREAM_H */