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