include/babeltrace2/trace-ir/trace-class.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_TRACE_CLASS_H
   8 #define BABELTRACE2_TRACE_IR_TRACE_CLASS_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-trace-cls Trace class
  26 @ingroup api-tir
  27
  28 @brief
  29     Class of \bt_p_trace.
  30
  31 A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
  32
  33 @image html trace-structure.png
  34
  35 In the illustration above, notice that a trace is an instance of a
  36 trace class.
  37
  38 A trace class is a \ref api-tir "trace IR" metadata object.
  39
  40 A trace class is a \ref api-fund-shared-object "shared object": get a
  41 new reference with bt_trace_class_get_ref() and put an existing
  42 reference with bt_trace_class_put_ref().
  43
  44 Some library functions \ref api-fund-freezing "freeze" trace classes on
  45 success. The documentation of those functions indicate this
  46 postcondition. With a frozen trace class, you can still:
  47
  48 - Create and add a \bt_p_stream_cls to it with
  49   bt_stream_class_create() or bt_stream_class_create_with_id().
  50 - Add a destruction listener to it with
  51   bt_trace_class_add_destruction_listener().
  52
  53 The type of a trace class is #bt_trace_class.
  54
  55 A trace class contains \bt_p_stream_cls. All the stream classes of a
  56 given trace class have unique
  57 \ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
  58 classes in a trace class with bt_trace_class_get_stream_class_count().
  59 Borrow a specific stream class from a trace class with
  60 bt_trace_class_borrow_stream_class_by_index(),
  61 bt_trace_class_borrow_stream_class_by_index_const(),
  62 bt_trace_class_borrow_stream_class_by_id(), or
  63 bt_trace_class_borrow_stream_class_by_id_const().
  64
  65 Set whether or not the \bt_p_stream_cls you create for a trace class get
  66 automatic numeric IDs with
  67 bt_trace_class_set_assigns_automatic_stream_class_id().
  68
  69 Create a default trace class from a \bt_self_comp with
  70 bt_trace_class_create().
  71
  72 Add to and remove a destruction listener from a trace class with
  73 bt_trace_class_add_destruction_listener() and
  74 bt_trace_class_remove_destruction_listener().
  75
  76 Get the effective \bt_mip version of the trace processing \bt_graph
  77 containing the \bt_comp from which a trace class was created with
  78 bt_trace_class_get_graph_mip_version().
  79
  80 <h1>Properties</h1>
  81
  82 A trace class has the following properties:
  83
  84 <dl>
  85   <dt>
  86     \anchor api-tir-trace-cls-prop-auto-sc-id
  87     Assigns automatic stream class IDs?
  88   </dt>
  89   <dd>
  90     Whether or not the stream classes you create and add to the trace
  91     class get \ref api-tir-stream-cls-prop-id "numeric IDs"
  92     automatically.
  93
  94     Depending on the value of this property, to create a stream class
  95     and add it to the trace class:
  96
  97     <dl>
  98       <dt>#BT_TRUE</dt>
  99       <dd>
 100         Use bt_stream_class_create().
 101       </dd>
 102
 103       <dt>#BT_FALSE</dt>
 104       <dd>
 105         Use bt_stream_class_create_with_id().
 106       </dd>
 107     </dl>
 108
 109     Use bt_trace_class_set_assigns_automatic_stream_class_id()
 110     and bt_trace_class_assigns_automatic_stream_class_id().
 111   </dd>
 112
 113   <dt>
 114     \anchor api-tir-trace-cls-prop-user-attrs
 115     \bt_dt_opt User attributes
 116   </dt>
 117   <dd>
 118     User attributes of the trace class.
 119
 120     User attributes are custom attributes attached to a trace class.
 121
 122     Use bt_trace_class_set_user_attributes(),
 123     bt_trace_class_borrow_user_attributes(), and
 124     bt_trace_class_borrow_user_attributes_const().
 125   </dd>
 126 </dl>
 127 */
 128
 129 /*! @{ */
 130
 131 /*!
 132 @name Type
 133 @{
 134
 135 @typedef struct bt_trace_class bt_trace_class;
 136
 137 @brief
 138     Trace class.
 139
 140 @}
 141 */
 142
 143 /*!
 144 @name Creation
 145 @{
 146 */
 147
 148 /*!
 149 @brief
 150     Creates a default trace class from the \bt_self_comp
 151     \bt_p{self_component}.
 152
 153 On success, the returned trace class has the following property values:
 154
 155 <table>
 156   <tr>
 157     <th>Property
 158     <th>Value
 159   <tr>
 160     <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
 161     <td>Yes
 162   <tr>
 163     <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
 164     <td>Empty \bt_map_val
 165 </table>
 166
 167 @param[in] self_component
 168     Self component from which to create the default trace class.
 169
 170 @returns
 171     New trace class reference, or \c NULL on memory error.
 172 */
 173 extern bt_trace_class *bt_trace_class_create(bt_self_component *self_component)
 174                 __BT_NOEXCEPT;
 175
 176 /*! @} */
 177
 178 /*!
 179 @name Stream class access
 180 @{
 181 */
 182
 183 /*!
 184 @brief
 185     Returns the number of \bt_p_stream_cls contained in the trace
 186     class \bt_p{trace_class}.
 187
 188 @param[in] trace_class
 189     Trace class of which to get the number of contained stream classes.
 190
 191 @returns
 192     Number of contained stream classes in \bt_p{trace_class}.
 193
 194 @bt_pre_not_null{trace_class}
 195 */
 196 extern uint64_t bt_trace_class_get_stream_class_count(
 197                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 198
 199 /*!
 200 @brief
 201     Borrows the \bt_stream_cls at index \bt_p{index} from the
 202     trace class \bt_p{trace_class}.
 203
 204 @param[in] trace_class
 205     Trace class from which to borrow the stream class at index
 206     \bt_p{index}.
 207 @param[in] index
 208     Index of the stream class to borrow from \bt_p{trace_class}.
 209
 210 @returns
 211     @parblock
 212     \em Borrowed reference of the stream class of
 213     \bt_p{trace_class} at index \bt_p{index}.
 214
 215     The returned pointer remains valid as long as \bt_p{trace_class}
 216     exists.
 217     @endparblock
 218
 219 @bt_pre_not_null{trace_class}
 220 @pre
 221     \bt_p{index} is less than the number of stream classes in
 222     \bt_p{trace_class} (as returned by
 223     bt_trace_class_get_stream_class_count()).
 224
 225 @sa bt_trace_class_get_stream_class_count() &mdash;
 226     Returns the number of stream classes contained in a trace class.
 227 @sa bt_trace_class_borrow_stream_class_by_index_const() &mdash;
 228     \c const version of this function.
 229 */
 230 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
 231                 bt_trace_class *trace_class, uint64_t index) __BT_NOEXCEPT;
 232
 233 /*!
 234 @brief
 235     Borrows the \bt_stream_cls at index \bt_p{index} from the
 236     trace class \bt_p{trace_class} (\c const version).
 237
 238 See bt_trace_class_borrow_stream_class_by_index().
 239 */
 240 extern const bt_stream_class *
 241 bt_trace_class_borrow_stream_class_by_index_const(
 242                 const bt_trace_class *trace_class,
 243                 uint64_t index) __BT_NOEXCEPT;
 244
 245 /*!
 246 @brief
 247     Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
 248     trace class \bt_p{trace_class}.
 249
 250 If there's no stream class having the numeric ID \bt_p{id} in
 251 \bt_p{trace_class}, this function returns \c NULL.
 252
 253 @param[in] trace_class
 254     Trace class from which to borrow the stream class having the
 255     numeric ID \bt_p{id}.
 256 @param[in] id
 257     ID of the stream class to borrow from \bt_p{trace_class}.
 258
 259 @returns
 260     @parblock
 261     \em Borrowed reference of the stream class of
 262     \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
 263     if none.
 264
 265     The returned pointer remains valid as long as \bt_p{trace_class}
 266     exists.
 267     @endparblock
 268
 269 @bt_pre_not_null{trace_class}
 270
 271 @sa bt_trace_class_borrow_stream_class_by_id_const() &mdash;
 272     \c const version of this function.
 273 */
 274 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
 275                 bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
 276
 277 /*!
 278 @brief
 279     Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
 280     trace class \bt_p{trace_class} (\c const version).
 281
 282 See bt_trace_class_borrow_stream_class_by_id().
 283 */
 284 extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
 285                 const bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
 286
 287 /*! @} */
 288
 289 /*!
 290 @name Properties
 291 @{
 292 */
 293
 294 /*!
 295 @brief
 296     Sets whether or not the trace class \bt_p{trace_class} automatically
 297     assigns a numeric ID to a \bt_stream_cls you create and add to it.
 298
 299 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
 300 property.
 301
 302 @param[in] trace_class
 303     Trace class of which to set whether or not it assigns automatic
 304     stream class IDs.
 305 @param[in] assigns_automatic_stream_class_id
 306     #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
 307     IDs.
 308
 309 @bt_pre_not_null{trace_class}
 310 @bt_pre_hot{trace_class}
 311
 312 @sa bt_trace_class_assigns_automatic_stream_class_id() &mdash;
 313     Returns whether or not a trace class automatically assigns
 314     stream class IDs.
 315 */
 316 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
 317                 bt_trace_class *trace_class,
 318                 bt_bool assigns_automatic_stream_class_id) __BT_NOEXCEPT;
 319
 320 /*!
 321 @brief
 322     Returns whether or not the trace class \bt_p{trace_class}
 323     automatically assigns a numeric ID to a \bt_stream_cls you create
 324     and add to it.
 325
 326 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
 327 property.
 328
 329 @param[in] trace_class
 330     Trace class of which to get whether or not it assigns automatic
 331     stream class IDs.
 332
 333 @returns
 334     #BT_TRUE if \bt_p{trace_class} automatically
 335     assigns stream class IDs.
 336
 337 @bt_pre_not_null{trace_class}
 338
 339 @sa bt_trace_class_set_assigns_automatic_stream_class_id() &mdash;
 340     Sets whether or not a trace class automatically assigns
 341     stream class IDs.
 342 */
 343 extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
 344                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 345
 346 /*!
 347 @brief
 348     Sets the user attributes of the trace class \bt_p{trace_class} to
 349     \bt_p{user_attributes}.
 350
 351 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
 352 property.
 353
 354 @note
 355     When you create a default trace class with bt_trace_class_create()
 356     or bt_trace_class_create_with_id(), the trace class's initial user
 357     attributes is an empty \bt_map_val. Therefore you can borrow it with
 358     bt_trace_class_borrow_user_attributes() and fill it directly
 359     instead of setting a new one with this function.
 360
 361 @param[in] trace_class
 362     Trace class of which to set the user attributes to
 363     \bt_p{user_attributes}.
 364 @param[in] user_attributes
 365     New user attributes of \bt_p{trace_class}.
 366
 367 @bt_pre_not_null{trace_class}
 368 @bt_pre_hot{trace_class}
 369 @bt_pre_not_null{user_attributes}
 370 @bt_pre_is_map_val{user_attributes}
 371
 372 @sa bt_trace_class_borrow_user_attributes() &mdash;
 373     Borrows the user attributes of a trace class.
 374 */
 375 extern void bt_trace_class_set_user_attributes(
 376                 bt_trace_class *trace_class,
 377                 const bt_value *user_attributes) __BT_NOEXCEPT;
 378
 379 /*!
 380 @brief
 381     Borrows the user attributes of the trace class \bt_p{trace_class}.
 382
 383 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
 384 property.
 385
 386 @note
 387     When you create a default trace class with bt_trace_class_create()
 388     or bt_trace_class_create_with_id(), the trace class's initial user
 389     attributes is an empty \bt_map_val.
 390
 391 @param[in] trace_class
 392     Trace class from which to borrow the user attributes.
 393
 394 @returns
 395     User attributes of \bt_p{trace_class} (a \bt_map_val).
 396
 397 @bt_pre_not_null{trace_class}
 398
 399 @sa bt_trace_class_set_user_attributes() &mdash;
 400     Sets the user attributes of a trace class.
 401 @sa bt_trace_class_borrow_user_attributes_const() &mdash;
 402     \c const version of this function.
 403 */
 404 extern bt_value *bt_trace_class_borrow_user_attributes(
 405                 bt_trace_class *trace_class) __BT_NOEXCEPT;
 406
 407 /*!
 408 @brief
 409     Borrows the user attributes of the trace class \bt_p{trace_class}
 410     (\c const version).
 411
 412 See bt_trace_class_borrow_user_attributes().
 413 */
 414 extern const bt_value *bt_trace_class_borrow_user_attributes_const(
 415                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 416
 417 /*!
 418 @brief
 419     Returns the effective \bt_mip (MIP) version of the trace processing
 420     \bt_graph containing the \bt_comp from which
 421     \bt_p{trace_class} was created.
 422
 423 @param[in] trace_class
 424     Trace class of which to get the effective MIP version.
 425
 426 @returns
 427     Effective MIP version of \bt_p{trace_class}.
 428
 429 @bt_pre_not_null{trace_class}
 430
 431 @sa bt_self_component_get_graph_mip_version() &mdash;
 432     Returns the effective MIP version of the trace processing
 433     graph which contains a given component.
 434 */
 435 extern uint64_t bt_trace_class_get_graph_mip_version(
 436                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 437
 438 /*! @} */
 439
 440 /*!
 441 @name Listeners
 442 @{
 443 */
 444
 445 /*!
 446 @brief
 447     User function for bt_trace_class_add_destruction_listener().
 448
 449 This is the user function type for a trace class destruction listener.
 450
 451 @param[in] trace_class
 452     Trace class being destroyed (\ref api-fund-freezing "frozen").
 453 @param[in] user_data
 454     User data, as passed as the \bt_p{user_data} parameter of
 455     bt_trace_class_add_destruction_listener().
 456
 457 @bt_pre_not_null{trace_class}
 458
 459 @post
 460     The reference count of \bt_p{trace_class} is not changed.
 461 @bt_post_no_error
 462
 463 @sa bt_trace_class_add_destruction_listener() &mdash;
 464     Adds a destruction listener to a trace class.
 465 */
 466 typedef void (* bt_trace_class_destruction_listener_func)(
 467                 const bt_trace_class *trace_class, void *user_data);
 468
 469 /*!
 470 @brief
 471     Status codes for bt_trace_class_add_destruction_listener().
 472 */
 473 typedef enum bt_trace_class_add_listener_status {
 474         /*!
 475         @brief
 476             Success.
 477         */
 478         BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK           = __BT_FUNC_STATUS_OK,
 479
 480         /*!
 481         @brief
 482             Out of memory.
 483         */
 484         BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 485 } bt_trace_class_add_listener_status;
 486
 487 /*!
 488 @brief
 489     Adds a destruction listener having the function \bt_p{user_func}
 490     to the trace class \bt_p{trace_class}.
 491
 492 All the destruction listener user functions of a trace class are called
 493 when it's being destroyed.
 494
 495 If \bt_p{listener_id} is not \c NULL, then this function, on success,
 496 sets \bt_p{*listener_id} to the ID of the added destruction listener
 497 within \bt_p{trace_class}. You can then use this ID to remove the
 498 added destruction listener with
 499 bt_trace_class_remove_destruction_listener().
 500
 501 @param[in] trace_class
 502     Trace class to add the destruction listener to.
 503 @param[in] user_func
 504     User function of the destruction listener to add to
 505     \bt_p{trace_class}.
 506 @param[in] user_data
 507     User data to pass as the \bt_p{user_data} parameter of
 508     \bt_p{user_func}.
 509 @param[out] listener_id
 510     <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
 511     is the ID of the added destruction listener within
 512     \bt_p{trace_class}.
 513
 514 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
 515     Success.
 516 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
 517     Out of memory.
 518
 519 @bt_pre_not_null{trace_class}
 520 @bt_pre_not_null{user_func}
 521
 522 @sa bt_trace_class_remove_destruction_listener() &mdash;
 523     Removes a destruction listener from a trace class.
 524 */
 525 extern bt_trace_class_add_listener_status
 526 bt_trace_class_add_destruction_listener(
 527         const bt_trace_class *trace_class,
 528         bt_trace_class_destruction_listener_func user_func,
 529         void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT;
 530
 531 /*!
 532 @brief
 533     Status codes for bt_trace_class_remove_destruction_listener().
 534 */
 535 typedef enum bt_trace_class_remove_listener_status {
 536         /*!
 537         @brief
 538             Success.
 539         */
 540         BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK                = __BT_FUNC_STATUS_OK,
 541
 542         /*!
 543         @brief
 544             Out of memory.
 545         */
 546         BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 547 } bt_trace_class_remove_listener_status;
 548
 549 /*!
 550 @brief
 551     Removes the destruction listener having the ID \bt_p{listener_id}
 552     from the trace class \bt_p{trace_class}.
 553
 554 The destruction listener to remove from \bt_p{trace_class} was
 555 previously added with bt_trace_class_add_destruction_listener().
 556
 557 You can call this function when \bt_p{trace_class} is
 558 \ref api-fund-freezing "frozen".
 559
 560 @param[in] trace_class
 561     Trace class from which to remove the destruction listener having
 562     the ID \bt_p{listener_id}.
 563 @param[in] listener_id
 564     ID of the destruction listener to remove from \bt_p{trace_class}.
 565
 566 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
 567     Success.
 568 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
 569     Out of memory.
 570
 571 @bt_pre_not_null{trace_class}
 572 @pre
 573     \bt_p{listener_id} is the ID of an existing destruction listener
 574     in \bt_p{trace_class}.
 575
 576 @sa bt_trace_class_add_destruction_listener() &mdash;
 577     Adds a destruction listener to a trace class.
 578 */
 579 extern bt_trace_class_remove_listener_status
 580 bt_trace_class_remove_destruction_listener(
 581                 const bt_trace_class *trace_class, bt_listener_id listener_id)
 582                 __BT_NOEXCEPT;
 583
 584 /*! @} */
 585
 586 /*!
 587 @name Reference count
 588 @{
 589 */
 590
 591 /*!
 592 @brief
 593     Increments the \ref api-fund-shared-object "reference count" of
 594     the trace class \bt_p{trace_class}.
 595
 596 @param[in] trace_class
 597     @parblock
 598     Trace class of which to increment the reference count.
 599
 600     Can be \c NULL.
 601     @endparblock
 602
 603 @sa bt_trace_class_put_ref() &mdash;
 604     Decrements the reference count of a trace class.
 605 */
 606 extern void bt_trace_class_get_ref(
 607                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 608
 609 /*!
 610 @brief
 611     Decrements the \ref api-fund-shared-object "reference count" of
 612     the trace class \bt_p{trace_class}.
 613
 614 @param[in] trace_class
 615     @parblock
 616     Trace class of which to decrement the reference count.
 617
 618     Can be \c NULL.
 619     @endparblock
 620
 621 @sa bt_trace_class_get_ref() &mdash;
 622     Increments the reference count of a trace class.
 623 */
 624 extern void bt_trace_class_put_ref(
 625                 const bt_trace_class *trace_class) __BT_NOEXCEPT;
 626
 627 /*!
 628 @brief
 629     Decrements the reference count of the trace class
 630     \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
 631
 632 @param _trace_class
 633     @parblock
 634     Trace class of which to decrement the reference count.
 635
 636     Can contain \c NULL.
 637     @endparblock
 638
 639 @bt_pre_assign_expr{_trace_class}
 640 */
 641 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class)          \
 642         do {                                                    \
 643                 bt_trace_class_put_ref(_trace_class);           \
 644                 (_trace_class) = NULL;                          \
 645         } while (0)
 646
 647 /*!
 648 @brief
 649     Decrements the reference count of the trace class \bt_p{_dst}, sets
 650     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 651
 652 This macro effectively moves a trace class reference from the expression
 653 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 654 \bt_p{_dst} reference.
 655
 656 @param _dst
 657     @parblock
 658     Destination expression.
 659
 660     Can contain \c NULL.
 661     @endparblock
 662 @param _src
 663     @parblock
 664     Source expression.
 665
 666     Can contain \c NULL.
 667     @endparblock
 668
 669 @bt_pre_assign_expr{_dst}
 670 @bt_pre_assign_expr{_src}
 671 */
 672 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src)     \
 673         do {                                    \
 674                 bt_trace_class_put_ref(_dst);   \
 675                 (_dst) = (_src);                \
 676                 (_src) = NULL;                  \
 677         } while (0)
 678
 679 /*! @} */
 680
 681 /*! @} */
 682
 683 #ifdef __cplusplus
 684 }
 685 #endif
 686
 687 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */