include/babeltrace2/trace-ir/trace-class.h

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