include/babeltrace2/trace-ir/event-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_EVENT_CLASS_H
   8 #define BABELTRACE2_TRACE_IR_EVENT_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-ev-cls Event class
  26 @ingroup api-tir
  27
  28 @brief
  29     Class of \bt_p_ev.
  30
  31 An <strong><em>event class</em></strong> is the class of \bt_p_ev,
  32 which \bt_p_ev_msg contain:
  33
  34 @image html trace-structure.png
  35
  36 In the illustration above, notice that:
  37
  38 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
  39   some of which are \bt_p_ev_msg.
  40 - An event message contains an \bt_ev.
  41 - An event is an instance of an event class.
  42 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
  43   instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
  44   which an event class contains.
  45
  46 An event class is a \ref api-tir "trace IR" metadata object.
  47
  48 An event class is a \ref api-fund-shared-object "shared object": get a
  49 new reference with bt_event_class_get_ref() and put an existing
  50 reference with bt_event_class_put_ref().
  51
  52 Some library functions \ref api-fund-freezing "freeze" event classes on
  53 success. The documentation of those functions indicate this
  54 postcondition.
  55
  56 The type of an event class is #bt_event_class.
  57
  58 A \bt_stream_cls contains event classes. All the event classes of a
  59 given stream class have unique
  60 \ref api-tir-ev-cls-prop-id "numeric IDs". Borrow the stream class
  61 which contains an event class with bt_event_class_borrow_stream_class()
  62 or bt_event_class_borrow_stream_class_const().
  63
  64 To create a default event class:
  65
  66 <dl>
  67   <dt>
  68     If bt_stream_class_assigns_automatic_event_class_id() returns
  69     #BT_TRUE (the default) for the stream class to use
  70   </dt>
  71   <dd>Use bt_event_class_create().</dd>
  72
  73   <dt>
  74     If bt_stream_class_assigns_automatic_event_class_id() returns
  75     #BT_FALSE for the stream class to use
  76   </dt>
  77   <dd>Use bt_event_class_create_with_id().</dd>
  78 </dl>
  79
  80 <h1>Properties</h1>
  81
  82 An event class has the following properties:
  83
  84 <dl>
  85   <dt>\anchor api-tir-ev-cls-prop-id Numeric ID</dt>
  86   <dd>
  87     Numeric ID, unique amongst the numeric IDs of the event class's
  88     \bt_stream_cls's event classes.
  89
  90     Depending on whether or not the event class's stream class
  91     automatically assigns event class IDs
  92     (see bt_stream_class_assigns_automatic_event_class_id()),
  93     set the event class's numeric ID on creation with
  94     bt_event_class_create() or
  95     bt_event_class_create_with_id().
  96
  97     You cannot change the numeric ID once the event class is created.
  98
  99     Get an event class's numeric ID with bt_event_class_get_id().
 100   </dd>
 101
 102   <dt>\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name</dt>
 103   <dd>
 104     Name of the event class.
 105
 106     Use bt_event_class_set_name() and bt_event_class_get_name().
 107   </dd>
 108
 109   <dt>\anchor api-tir-ev-cls-prop-log-lvl \bt_dt_opt Log level</dt>
 110   <dd>
 111     Log level of the event class.
 112
 113     The event class's log level corresponds to the log level of the
 114     tracer's original instrumentation point.
 115
 116     Use bt_event_class_set_log_level() and
 117     bt_event_class_get_log_level().
 118   </dd>
 119
 120   <dt>
 121     \anchor api-tir-ev-cls-prop-emf-uri
 122     \bt_dt_opt Eclipse Modeling Framework (EMF) URI
 123   </dt>
 124   <dd>
 125     EMF URI of the event class.
 126
 127     Use bt_event_class_set_emf_uri() and
 128     bt_event_class_get_emf_uri().
 129   </dd>
 130
 131   <dt>
 132     \anchor api-tir-ev-cls-prop-p-fc
 133     \bt_dt_opt Payload field class
 134   </dt>
 135   <dd>
 136     Payload \bt_fc of the event class.
 137
 138     The payload of an event class instance (\bt_ev) contains the
 139     event's main data.
 140
 141     Use bt_event_class_set_payload_field_class()
 142     bt_event_class_borrow_payload_field_class(),
 143     and bt_event_class_borrow_payload_field_class_const().
 144   </dd>
 145
 146   <dt>
 147     \anchor api-tir-ev-cls-prop-sc-fc
 148     \bt_dt_opt Specific context field class
 149   </dt>
 150   <dd>
 151     Specific context \bt_fc of the event class.
 152
 153     The specific context of an event class instance (\bt_ev) contains
 154     any contextual data of which the layout is specific to the
 155     event's class and which does not belong to the payload.
 156
 157     Use bt_event_class_set_specific_context_field_class()
 158     bt_event_class_borrow_specific_context_field_class(),
 159     and bt_event_class_borrow_specific_context_field_class_const().
 160   </dd>
 161
 162   <dt>
 163     \anchor api-tir-ev-cls-prop-user-attrs
 164     \bt_dt_opt User attributes
 165   </dt>
 166   <dd>
 167     User attributes of the event class.
 168
 169     User attributes are custom attributes attached to an event class.
 170
 171     Use bt_event_class_set_user_attributes(),
 172     bt_event_class_borrow_user_attributes(), and
 173     bt_event_class_borrow_user_attributes_const().
 174   </dd>
 175 </dl>
 176 */
 177
 178 /*! @{ */
 179
 180 /*!
 181 @name Type
 182 @{
 183
 184 @typedef struct bt_event_class bt_event_class;
 185
 186 @brief
 187     Event class.
 188
 189 @}
 190 */
 191
 192 /*!
 193 @name Creation
 194 @{
 195 */
 196
 197 /*!
 198 @brief
 199     Creates a default event class and adds it to the \bt_stream_cls
 200     \bt_p{stream_class}.
 201
 202 @attention
 203     @parblock
 204     Only use this function if
 205
 206     @code
 207     bt_stream_class_assigns_automatic_event_class_id(stream_class)
 208     @endcode
 209
 210     returns #BT_TRUE.
 211
 212     Otherwise, use bt_event_class_create_with_id().
 213     @endparblock
 214
 215 On success, the returned event class has the following property values:
 216
 217 <table>
 218   <tr>
 219     <th>Property
 220     <th>Value
 221   <tr>
 222     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
 223     <td>Automatically assigned by \bt_p{stream_class}
 224   <tr>
 225     <td>\ref api-tir-ev-cls-prop-name "Name"
 226     <td>\em None
 227   <tr>
 228     <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
 229     <td>\em None
 230   <tr>
 231     <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
 232     <td>\em None
 233   <tr>
 234     <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
 235     <td>\em None
 236   <tr>
 237     <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
 238     <td>\em None
 239   <tr>
 240     <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
 241     <td>Empty \bt_map_val
 242 </table>
 243
 244 @param[in] stream_class
 245     Stream class to add the created event class to.
 246
 247 @returns
 248     New event class reference, or \c NULL on memory error.
 249
 250 @bt_pre_not_null{stream_class}
 251 @pre
 252     <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
 253     returns #BT_TRUE.
 254
 255 @bt_post_success_frozen{stream_class}
 256
 257 @sa bt_event_class_create_with_id() &mdash;
 258     Creates an event class with a specific numeric ID and adds it to a
 259     stream class.
 260 */
 261 extern bt_event_class *bt_event_class_create(
 262                 bt_stream_class *stream_class);
 263
 264 /*!
 265 @brief
 266     Creates a default event class with the numeric ID \bt_p{id} and adds
 267     it to the \bt_stream_cls \bt_p{stream_class}.
 268
 269 @attention
 270     @parblock
 271     Only use this function if
 272
 273     @code
 274     bt_stream_class_assigns_automatic_event_class_id(stream_class)
 275     @endcode
 276
 277     returns #BT_FALSE.
 278
 279     Otherwise, use bt_event_class_create().
 280     @endparblock
 281
 282 On success, the returned event class has the following property values:
 283
 284 <table>
 285   <tr>
 286     <th>Property
 287     <th>Value
 288   <tr>
 289     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
 290     <td>\bt_p{id}
 291   <tr>
 292     <td>\ref api-tir-ev-cls-prop-name "Name"
 293     <td>\em None
 294   <tr>
 295     <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
 296     <td>\em None
 297   <tr>
 298     <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
 299     <td>\em None
 300   <tr>
 301     <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
 302     <td>\em None
 303   <tr>
 304     <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
 305     <td>\em None
 306   <tr>
 307     <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
 308     <td>Empty \bt_map_val
 309 </table>
 310
 311 @param[in] stream_class
 312     Stream class to add the created event class to.
 313 @param[in] id
 314     Numeric ID of the event class to create and add to
 315     \bt_p{stream_class}.
 316
 317 @returns
 318     New event class reference, or \c NULL on memory error.
 319
 320 @bt_pre_not_null{stream_class}
 321 @pre
 322     <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
 323     returns #BT_FALSE.
 324 @pre
 325     \bt_p{stream_class} does not contain an event class with the numeric
 326     ID \bt_p{id}.
 327
 328 @bt_post_success_frozen{stream_class}
 329
 330 @sa bt_event_class_create() &mdash;
 331     Creates an event class with an automatic numeric ID and adds it to a
 332     stream class.
 333 */
 334 extern bt_event_class *bt_event_class_create_with_id(
 335                 bt_stream_class *stream_class, uint64_t id);
 336
 337 /*! @} */
 338
 339 /*!
 340 @name Stream class access
 341 @{
 342 */
 343
 344 /*!
 345 @brief
 346     Borrows the \bt_stream_cls which contains the event class
 347     \bt_p{event_class}.
 348
 349 @param[in] event_class
 350     Event class from which to borrow the stream class which contains it.
 351
 352 @returns
 353     Stream class which contains \bt_p{event_class}.
 354
 355 @bt_pre_not_null{event_class}
 356
 357 @sa bt_event_class_borrow_stream_class_const() &mdash;
 358     \c const version of this function.
 359 */
 360 extern bt_stream_class *bt_event_class_borrow_stream_class(
 361                 bt_event_class *event_class);
 362
 363 /*!
 364 @brief
 365     Borrows the \bt_stream_cls which contains the event class
 366     \bt_p{event_class} (\c const version).
 367
 368 See bt_event_class_borrow_stream_class().
 369 */
 370 extern const bt_stream_class *bt_event_class_borrow_stream_class_const(
 371                 const bt_event_class *event_class);
 372
 373 /*! @} */
 374
 375 /*!
 376 @name Properties
 377 @{
 378 */
 379
 380 /*!
 381 @brief
 382     Returns the numeric ID of the event class \bt_p{event_class}.
 383
 384 See the \ref api-tir-ev-cls-prop-id "numeric ID" property.
 385
 386 @param[in] event_class
 387     Event class of which to get the numeric ID.
 388
 389 @returns
 390     Numeric ID of \bt_p{event_class}.
 391
 392 @bt_pre_not_null{event_class}
 393
 394 @sa bt_event_class_create_with_id() &mdash;
 395     Creates an event class with a specific numeric ID and adds it to a
 396     stream class.
 397 */
 398 extern uint64_t bt_event_class_get_id(const bt_event_class *event_class);
 399
 400 /*!
 401 @brief
 402     Status codes for bt_event_class_set_name().
 403 */
 404 typedef enum bt_event_class_set_name_status {
 405         /*!
 406         @brief
 407             Success.
 408         */
 409         BT_EVENT_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
 410
 411         /*!
 412         @brief
 413             Out of memory.
 414         */
 415         BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 416 } bt_event_class_set_name_status;
 417
 418 /*!
 419 @brief
 420     Sets the name of the event class \bt_p{event_class} to
 421     a copy of \bt_p{name}.
 422
 423 See the \ref api-tir-ev-cls-prop-name "name" property.
 424
 425 @param[in] event_class
 426     Event class of which to set the name to \bt_p{name}.
 427 @param[in] name
 428     New name of \bt_p{event_class} (copied).
 429
 430 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_OK
 431     Success.
 432 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 433     Out of memory.
 434
 435 @bt_pre_not_null{event_class}
 436 @bt_pre_hot{event_class}
 437 @bt_pre_not_null{name}
 438
 439 @sa bt_event_class_get_name() &mdash;
 440     Returns the name of an event class.
 441 */
 442 extern bt_event_class_set_name_status bt_event_class_set_name(
 443                 bt_event_class *event_class, const char *name);
 444
 445 /*!
 446 @brief
 447     Returns the name of the event class \bt_p{event_class}.
 448
 449 See the \ref api-tir-ev-cls-prop-name "name" property.
 450
 451 If \bt_p{event_class} has no name, this function returns \c NULL.
 452
 453 @param[in] event_class
 454     Event class of which to get the name.
 455
 456 @returns
 457     @parblock
 458     Name of \bt_p{event_class}, or \c NULL if none.
 459
 460     The returned pointer remains valid as long as \bt_p{event_class}
 461     is not modified.
 462     @endparblock
 463
 464 @bt_pre_not_null{event_class}
 465
 466 @sa bt_event_class_set_name() &mdash;
 467     Sets the name of an event class.
 468 */
 469 extern const char *bt_event_class_get_name(const bt_event_class *event_class);
 470
 471 /*!
 472 @brief
 473     Event class log level enumerators.
 474 */
 475 typedef enum bt_event_class_log_level {
 476         /*!
 477         @brief
 478             System is unusable.
 479         */
 480         BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY              = 0,
 481
 482         /*!
 483         @brief
 484             Action must be taken immediately.
 485         */
 486         BT_EVENT_CLASS_LOG_LEVEL_ALERT                  = 1,
 487
 488         /*!
 489         @brief
 490             Critical conditions.
 491         */
 492         BT_EVENT_CLASS_LOG_LEVEL_CRITICAL               = 2,
 493
 494         /*!
 495         @brief
 496             Error conditions.
 497         */
 498         BT_EVENT_CLASS_LOG_LEVEL_ERROR                  = 3,
 499
 500         /*!
 501         @brief
 502             Warning conditions.
 503         */
 504         BT_EVENT_CLASS_LOG_LEVEL_WARNING                = 4,
 505
 506         /*!
 507         @brief
 508             Normal, but significant, condition.
 509         */
 510         BT_EVENT_CLASS_LOG_LEVEL_NOTICE                 = 5,
 511
 512         /*!
 513         @brief
 514             Informational message.
 515         */
 516         BT_EVENT_CLASS_LOG_LEVEL_INFO                   = 6,
 517
 518         /*!
 519         @brief
 520             Debugging information with system-level scope
 521             (set of programs).
 522         */
 523         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM           = 7,
 524
 525         /*!
 526         @brief
 527             Debugging information with program-level scope
 528             (set of processes).
 529         */
 530         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM          = 8,
 531
 532         /*!
 533         @brief
 534             Debugging information with process-level scope
 535             (set of modules).
 536         */
 537         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS          = 9,
 538
 539         /*!
 540         @brief
 541             Debugging information with module (executable/library) scope
 542             (set of units).
 543         */
 544         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE           = 10,
 545
 546         /*!
 547         @brief
 548             Debugging information with compilation unit scope
 549             (set of functions).
 550         */
 551         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT             = 11,
 552
 553         /*!
 554         @brief
 555             Debugging information with function-level scope.
 556         */
 557         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION         = 12,
 558
 559         /*!
 560         @brief
 561             Debugging information with function-level scope.
 562         */
 563         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE             = 13,
 564
 565         /*!
 566         @brief
 567             Debugging-level message.
 568         */
 569         BT_EVENT_CLASS_LOG_LEVEL_DEBUG                  = 14,
 570 } bt_event_class_log_level;
 571
 572 /*!
 573 @brief
 574     Sets the log level of the event class \bt_p{event_class} to
 575     \bt_p{log_level}.
 576
 577 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 578
 579 @param[in] event_class
 580     Event class of which to set the log level to \bt_p{log_level}.
 581 @param[in] log_level
 582     New log level of \bt_p{event_class}.
 583
 584 @bt_pre_not_null{event_class}
 585 @bt_pre_hot{event_class}
 586
 587 @sa bt_event_class_get_log_level() &mdash;
 588     Returns the log level of an event class.
 589 */
 590 extern void bt_event_class_set_log_level(bt_event_class *event_class,
 591                 bt_event_class_log_level log_level);
 592
 593 /*!
 594 @brief
 595     Returns the log level of the event class \bt_p{event_class}.
 596
 597 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 598
 599 @param[in] event_class
 600     Event class of which to get the log level.
 601 @param[out] log_level
 602     <strong>If this function returns
 603     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*log_level} is
 604     the log level of \bt_p{event_class}.
 605
 606 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
 607     The log level of \bt_p{event_class} is available.
 608 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
 609     The log level of \bt_p{event_class} is not available.
 610
 611 @bt_pre_not_null{event_class}
 612 @bt_pre_not_null{log_level}
 613
 614 @sa bt_event_class_set_log_level() &mdash;
 615     Sets the log level of an event class.
 616 */
 617 extern bt_property_availability bt_event_class_get_log_level(
 618                 const bt_event_class *event_class,
 619                 bt_event_class_log_level *log_level);
 620
 621 /*!
 622 @brief
 623     Status codes for bt_event_class_set_emf_uri().
 624 */
 625 typedef enum bt_event_class_set_emf_uri_status {
 626         /*!
 627         @brief
 628             Success.
 629         */
 630         BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK            = __BT_FUNC_STATUS_OK,
 631
 632         /*!
 633         @brief
 634             Out of memory.
 635         */
 636         BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 637 } bt_event_class_set_emf_uri_status;
 638
 639 /*!
 640 @brief
 641     Sets the Eclipse Modeling Framework (EMF) URI of the event class
 642     \bt_p{event_class} to a copy of \bt_p{emf_uri}.
 643
 644 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 645
 646 @param[in] event_class
 647     Event class of which to set the EMF URI to \bt_p{emf_uri}.
 648 @param[in] emf_uri
 649     New EMF URI of \bt_p{event_class} (copied).
 650
 651 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK
 652     Success.
 653 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR
 654     Out of memory.
 655
 656 @bt_pre_not_null{event_class}
 657 @bt_pre_hot{event_class}
 658 @bt_pre_not_null{emf_uri}
 659
 660 @sa bt_event_class_get_emf_uri() &mdash;
 661     Returns the EMF URI of an event class.
 662 */
 663 extern bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri(
 664                 bt_event_class *event_class, const char *emf_uri);
 665
 666 /*!
 667 @brief
 668     Returns the Eclipse Modeling Framework (EMF) URI of the event
 669     class \bt_p{event_class}.
 670
 671 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 672
 673 If \bt_p{event_class} has no EMF URI, this function returns \c NULL.
 674
 675 @param[in] event_class
 676     Event class of which to get the EMF URI.
 677
 678 @returns
 679     @parblock
 680     EMF URI of \bt_p{event_class}, or \c NULL if none.
 681
 682     The returned pointer remains valid as long as \bt_p{event_class}
 683     is not modified.
 684     @endparblock
 685
 686 @bt_pre_not_null{event_class}
 687
 688 @sa bt_event_class_set_emf_uri() &mdash;
 689     Sets the EMF URI of an event class.
 690 */
 691 extern const char *bt_event_class_get_emf_uri(
 692                 const bt_event_class *event_class);
 693
 694 /*!
 695 @brief
 696     Status codes for bt_event_class_set_payload_field_class() and
 697     bt_event_class_set_specific_context_field_class().
 698 */
 699 typedef enum bt_event_class_set_field_class_status {
 700         /*!
 701         @brief
 702             Success.
 703         */
 704         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK                = __BT_FUNC_STATUS_OK,
 705
 706         /*!
 707         @brief
 708             Out of memory.
 709         */
 710         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 711 } bt_event_class_set_field_class_status;
 712
 713 /*!
 714 @brief
 715     Sets the payload \bt_fc of the event class
 716     \bt_p{event_class} to \bt_p{field_class}.
 717
 718 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 719
 720 @param[in] event_class
 721     Event class of which to set the payload field class to
 722     \bt_p{field_class}.
 723 @param[in] field_class
 724     New payload field class of \bt_p{event_class}.
 725
 726 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
 727     Success.
 728 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
 729     Out of memory.
 730
 731 @bt_pre_not_null{event_class}
 732 @bt_pre_hot{event_class}
 733 @bt_pre_not_null{field_class}
 734 @bt_pre_is_struct_fc{field_class}
 735 @pre
 736     \bt_p{field_class}, or any of its contained field classes,
 737     is not already part of a \bt_stream_cls or of an event class.
 738 @pre
 739     If any of the field classes recursively contained in
 740     \bt_p{field_class} has a
 741     \ref api-tir-fc-link "link to another field class", it must honor
 742     the field class link rules.
 743
 744 @bt_post_success_frozen{field_class}
 745
 746 @sa bt_event_class_borrow_payload_field_class() &mdash;
 747     Borrows the payload field class of an event class.
 748 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 749     Borrows the payload field class of an event class
 750     (\c const version).
 751 */
 752 extern bt_event_class_set_field_class_status
 753 bt_event_class_set_payload_field_class(bt_event_class *event_class,
 754                 bt_field_class *field_class);
 755
 756 /*!
 757 @brief
 758     Borrows the payload \bt_fc from the event class \bt_p{event_class}.
 759
 760 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 761
 762 If \bt_p{event_class} has no payload field class, this function
 763 returns \c NULL.
 764
 765 @param[in] event_class
 766     Event class from which to borrow the payload field class.
 767
 768 @returns
 769     \em Borrowed reference of the payload field class of
 770     \bt_p{event_class}, or \c NULL if none.
 771
 772 @bt_pre_not_null{event_class}
 773
 774 @sa bt_event_class_set_payload_field_class() &mdash;
 775     Sets the payload field class of an event class.
 776 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 777     \c const version of this function.
 778 */
 779 extern bt_field_class *bt_event_class_borrow_payload_field_class(
 780                 bt_event_class *event_class);
 781
 782 /*!
 783 @brief
 784     Borrows the payload \bt_fc from the event class \bt_p{event_class}
 785     (\c const version).
 786
 787 See bt_event_class_borrow_payload_field_class().
 788 */
 789 extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
 790                 const bt_event_class *event_class);
 791
 792 /*!
 793 @brief
 794     Sets the specific context \bt_fc of the event class
 795     \bt_p{event_class} to \bt_p{field_class}.
 796
 797 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
 798 property.
 799
 800 @param[in] event_class
 801     Event class of which to set the specific context field class to
 802     \bt_p{field_class}.
 803 @param[in] field_class
 804     New specific context field class of \bt_p{event_class}.
 805
 806 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
 807     Success.
 808 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
 809     Out of memory.
 810
 811 @bt_pre_not_null{event_class}
 812 @bt_pre_hot{event_class}
 813 @bt_pre_not_null{field_class}
 814 @bt_pre_is_struct_fc{field_class}
 815 @pre
 816     \bt_p{field_class}, or any of its contained field classes,
 817     is not already part of a \bt_stream_cls or of an event class.
 818 @pre
 819     If any of the field classes recursively contained in
 820     \bt_p{field_class} has a
 821     \ref api-tir-fc-link "link to another field class", it must honor
 822     the field class link rules.
 823
 824 @bt_post_success_frozen{field_class}
 825
 826 @sa bt_event_class_borrow_specific_context_field_class() &mdash;
 827     Borrows the specific context field class of an event class.
 828 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
 829     Borrows the specific context field class of an event class
 830     (\c const version).
 831 */
 832 extern bt_event_class_set_field_class_status
 833 bt_event_class_set_specific_context_field_class(bt_event_class *event_class,
 834                 bt_field_class *field_class);
 835
 836 /*!
 837 @brief
 838     Borrows the specific context \bt_fc from the event class
 839     \bt_p{event_class}.
 840
 841 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
 842 property.
 843
 844 If \bt_p{event_class} has no specific context field class, this function
 845 returns \c NULL.
 846
 847 @param[in] event_class
 848     Event class from which to borrow the specific context field class.
 849
 850 @returns
 851     \em Borrowed reference of the specific context field class of
 852     \bt_p{event_class}, or \c NULL if none.
 853
 854 @bt_pre_not_null{event_class}
 855
 856 @sa bt_event_class_set_specific_context_field_class() &mdash;
 857     Sets the specific context field class of an event class.
 858 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
 859     \c const version of this function.
 860 */
 861 extern bt_field_class *
 862 bt_event_class_borrow_specific_context_field_class(bt_event_class *event_class);
 863
 864 /*!
 865 @brief
 866     Borrows the specific context \bt_fc from the event class
 867     \bt_p{event_class} (\c const version).
 868
 869 See bt_event_class_borrow_specific_context_field_class().
 870 */
 871 extern const bt_field_class *
 872 bt_event_class_borrow_specific_context_field_class_const(
 873                 const bt_event_class *event_class);
 874
 875 /*!
 876 @brief
 877     Sets the user attributes of the event class \bt_p{event_class} to
 878     \bt_p{user_attributes}.
 879
 880 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
 881
 882 @note
 883     When you create a default event class with bt_event_class_create()
 884     or bt_event_class_create_with_id(), the event class's initial user
 885     attributes is an empty \bt_map_val. Therefore you can borrow it with
 886     bt_event_class_borrow_user_attributes() and fill it directly instead
 887     of setting a new one with this function.
 888
 889 @param[in] event_class
 890     Event class of which to set the user attributes to
 891     \bt_p{user_attributes}.
 892 @param[in] user_attributes
 893     New user attributes of \bt_p{event_class}.
 894
 895 @bt_pre_not_null{event_class}
 896 @bt_pre_hot{event_class}
 897 @bt_pre_not_null{user_attributes}
 898 @bt_pre_is_map_val{user_attributes}
 899
 900 @sa bt_event_class_borrow_user_attributes() &mdash;
 901     Borrows the user attributes of an event class.
 902 */
 903 extern void bt_event_class_set_user_attributes(
 904                 bt_event_class *event_class, const bt_value *user_attributes);
 905
 906 /*!
 907 @brief
 908     Borrows the user attributes of the event class \bt_p{event_class}.
 909
 910 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
 911
 912 @note
 913     When you create a default event class with bt_event_class_create()
 914     or bt_event_class_create_with_id(), the event class's initial user
 915     attributes is an empty \bt_map_val.
 916
 917 @param[in] event_class
 918     Event class from which to borrow the user attributes.
 919
 920 @returns
 921     User attributes of \bt_p{event_class} (a \bt_map_val).
 922
 923 @bt_pre_not_null{event_class}
 924
 925 @sa bt_event_class_set_user_attributes() &mdash;
 926     Sets the user attributes of an event class.
 927 @sa bt_event_class_borrow_user_attributes_const() &mdash;
 928     \c const version of this function.
 929 */
 930 extern bt_value *bt_event_class_borrow_user_attributes(
 931                 bt_event_class *event_class);
 932
 933 /*!
 934 @brief
 935     Borrows the user attributes of the event class \bt_p{event_class}
 936     (\c const version).
 937
 938 See bt_event_class_borrow_user_attributes().
 939 */
 940 extern const bt_value *bt_event_class_borrow_user_attributes_const(
 941                 const bt_event_class *event_class);
 942
 943 /*! @} */
 944
 945 /*!
 946 @name Reference count
 947 @{
 948 */
 949
 950 /*!
 951 @brief
 952     Increments the \ref api-fund-shared-object "reference count" of
 953     the event class \bt_p{event_class}.
 954
 955 @param[in] event_class
 956     @parblock
 957     Event class of which to increment the reference count.
 958
 959     Can be \c NULL.
 960     @endparblock
 961
 962 @sa bt_event_class_put_ref() &mdash;
 963     Decrements the reference count of an event class.
 964 */
 965 extern void bt_event_class_get_ref(const bt_event_class *event_class);
 966
 967 /*!
 968 @brief
 969     Decrements the \ref api-fund-shared-object "reference count" of
 970     the event class \bt_p{event_class}.
 971
 972 @param[in] event_class
 973     @parblock
 974     Event class of which to decrement the reference count.
 975
 976     Can be \c NULL.
 977     @endparblock
 978
 979 @sa bt_event_class_get_ref() &mdash;
 980     Increments the reference count of an event class.
 981 */
 982 extern void bt_event_class_put_ref(const bt_event_class *event_class);
 983
 984 /*!
 985 @brief
 986     Decrements the reference count of the event class
 987     \bt_p{_event_class}, and then sets \bt_p{_event_class} to \c NULL.
 988
 989 @param _event_class
 990     @parblock
 991     Event class of which to decrement the reference count.
 992
 993     Can contain \c NULL.
 994     @endparblock
 995
 996 @bt_pre_assign_expr{_event_class}
 997 */
 998 #define BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class)  \
 999         do {                                            \
1000                 bt_event_class_put_ref(_event_class);   \
1001                 (_event_class) = NULL;                  \
1002         } while (0)
1003
1004 /*!
1005 @brief
1006     Decrements the reference count of the event class \bt_p{_dst}, sets
1007     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1008
1009 This macro effectively moves an event class reference from the expression
1010 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1011 \bt_p{_dst} reference.
1012
1013 @param _dst
1014     @parblock
1015     Destination expression.
1016
1017     Can contain \c NULL.
1018     @endparblock
1019 @param _src
1020     @parblock
1021     Source expression.
1022
1023     Can contain \c NULL.
1024     @endparblock
1025
1026 @bt_pre_assign_expr{_dst}
1027 @bt_pre_assign_expr{_src}
1028 */
1029 #define BT_EVENT_CLASS_MOVE_REF(_dst, _src)     \
1030         do {                                    \
1031                 bt_event_class_put_ref(_dst);   \
1032                 (_dst) = (_src);                \
1033                 (_src) = NULL;                  \
1034         } while (0)
1035
1036 /*! @} */
1037
1038 /*! @} */
1039
1040 #ifdef __cplusplus
1041 }
1042 #endif
1043
1044 #endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_H */