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