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