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