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) __BT_NOEXCEPT;
 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) __BT_NOEXCEPT;
 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) __BT_NOEXCEPT;
 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) __BT_NOEXCEPT;
 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(
 399                 const bt_event_class *event_class) __BT_NOEXCEPT;
 400
 401 /*!
 402 @brief
 403     Status codes for bt_event_class_set_name().
 404 */
 405 typedef enum bt_event_class_set_name_status {
 406         /*!
 407         @brief
 408             Success.
 409         */
 410         BT_EVENT_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
 411
 412         /*!
 413         @brief
 414             Out of memory.
 415         */
 416         BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 417 } bt_event_class_set_name_status;
 418
 419 /*!
 420 @brief
 421     Sets the name of the event class \bt_p{event_class} to
 422     a copy of \bt_p{name}.
 423
 424 See the \ref api-tir-ev-cls-prop-name "name" property.
 425
 426 @param[in] event_class
 427     Event class of which to set the name to \bt_p{name}.
 428 @param[in] name
 429     New name of \bt_p{event_class} (copied).
 430
 431 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_OK
 432     Success.
 433 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 434     Out of memory.
 435
 436 @bt_pre_not_null{event_class}
 437 @bt_pre_hot{event_class}
 438 @bt_pre_not_null{name}
 439
 440 @sa bt_event_class_get_name() &mdash;
 441     Returns the name of an event class.
 442 */
 443 extern bt_event_class_set_name_status bt_event_class_set_name(
 444                 bt_event_class *event_class, const char *name) __BT_NOEXCEPT;
 445
 446 /*!
 447 @brief
 448     Returns the name of the event class \bt_p{event_class}.
 449
 450 See the \ref api-tir-ev-cls-prop-name "name" property.
 451
 452 If \bt_p{event_class} has no name, this function returns \c NULL.
 453
 454 @param[in] event_class
 455     Event class of which to get the name.
 456
 457 @returns
 458     @parblock
 459     Name of \bt_p{event_class}, or \c NULL if none.
 460
 461     The returned pointer remains valid as long as \bt_p{event_class}
 462     is not modified.
 463     @endparblock
 464
 465 @bt_pre_not_null{event_class}
 466
 467 @sa bt_event_class_set_name() &mdash;
 468     Sets the name of an event class.
 469 */
 470 extern const char *bt_event_class_get_name(
 471                 const bt_event_class *event_class) __BT_NOEXCEPT;
 472
 473 /*!
 474 @brief
 475     Event class log level enumerators.
 476 */
 477 typedef enum bt_event_class_log_level {
 478         /*!
 479         @brief
 480             System is unusable.
 481         */
 482         BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY              = 0,
 483
 484         /*!
 485         @brief
 486             Action must be taken immediately.
 487         */
 488         BT_EVENT_CLASS_LOG_LEVEL_ALERT                  = 1,
 489
 490         /*!
 491         @brief
 492             Critical conditions.
 493         */
 494         BT_EVENT_CLASS_LOG_LEVEL_CRITICAL               = 2,
 495
 496         /*!
 497         @brief
 498             Error conditions.
 499         */
 500         BT_EVENT_CLASS_LOG_LEVEL_ERROR                  = 3,
 501
 502         /*!
 503         @brief
 504             Warning conditions.
 505         */
 506         BT_EVENT_CLASS_LOG_LEVEL_WARNING                = 4,
 507
 508         /*!
 509         @brief
 510             Normal, but significant, condition.
 511         */
 512         BT_EVENT_CLASS_LOG_LEVEL_NOTICE                 = 5,
 513
 514         /*!
 515         @brief
 516             Informational message.
 517         */
 518         BT_EVENT_CLASS_LOG_LEVEL_INFO                   = 6,
 519
 520         /*!
 521         @brief
 522             Debugging information with system-level scope
 523             (set of programs).
 524         */
 525         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM           = 7,
 526
 527         /*!
 528         @brief
 529             Debugging information with program-level scope
 530             (set of processes).
 531         */
 532         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM          = 8,
 533
 534         /*!
 535         @brief
 536             Debugging information with process-level scope
 537             (set of modules).
 538         */
 539         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS          = 9,
 540
 541         /*!
 542         @brief
 543             Debugging information with module (executable/library) scope
 544             (set of units).
 545         */
 546         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE           = 10,
 547
 548         /*!
 549         @brief
 550             Debugging information with compilation unit scope
 551             (set of functions).
 552         */
 553         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT             = 11,
 554
 555         /*!
 556         @brief
 557             Debugging information with function-level scope.
 558         */
 559         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION         = 12,
 560
 561         /*!
 562         @brief
 563             Debugging information with function-level scope.
 564         */
 565         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE             = 13,
 566
 567         /*!
 568         @brief
 569             Debugging-level message.
 570         */
 571         BT_EVENT_CLASS_LOG_LEVEL_DEBUG                  = 14,
 572 } bt_event_class_log_level;
 573
 574 /*!
 575 @brief
 576     Sets the log level of the event class \bt_p{event_class} to
 577     \bt_p{log_level}.
 578
 579 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 580
 581 @param[in] event_class
 582     Event class of which to set the log level to \bt_p{log_level}.
 583 @param[in] log_level
 584     New log level of \bt_p{event_class}.
 585
 586 @bt_pre_not_null{event_class}
 587 @bt_pre_hot{event_class}
 588
 589 @sa bt_event_class_get_log_level() &mdash;
 590     Returns the log level of an event class.
 591 */
 592 extern void bt_event_class_set_log_level(bt_event_class *event_class,
 593                 bt_event_class_log_level log_level) __BT_NOEXCEPT;
 594
 595 /*!
 596 @brief
 597     Returns the log level of the event class \bt_p{event_class}.
 598
 599 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 600
 601 @param[in] event_class
 602     Event class of which to get the log level.
 603 @param[out] log_level
 604     <strong>If this function returns
 605     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*log_level} is
 606     the log level of \bt_p{event_class}.
 607
 608 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
 609     The log level of \bt_p{event_class} is available.
 610 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
 611     The log level of \bt_p{event_class} is not available.
 612
 613 @bt_pre_not_null{event_class}
 614 @bt_pre_not_null{log_level}
 615
 616 @sa bt_event_class_set_log_level() &mdash;
 617     Sets the log level of an event class.
 618 */
 619 extern bt_property_availability bt_event_class_get_log_level(
 620                 const bt_event_class *event_class,
 621                 bt_event_class_log_level *log_level) __BT_NOEXCEPT;
 622
 623 /*!
 624 @brief
 625     Status codes for bt_event_class_set_emf_uri().
 626 */
 627 typedef enum bt_event_class_set_emf_uri_status {
 628         /*!
 629         @brief
 630             Success.
 631         */
 632         BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK            = __BT_FUNC_STATUS_OK,
 633
 634         /*!
 635         @brief
 636             Out of memory.
 637         */
 638         BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 639 } bt_event_class_set_emf_uri_status;
 640
 641 /*!
 642 @brief
 643     Sets the Eclipse Modeling Framework (EMF) URI of the event class
 644     \bt_p{event_class} to a copy of \bt_p{emf_uri}.
 645
 646 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 647
 648 @param[in] event_class
 649     Event class of which to set the EMF URI to \bt_p{emf_uri}.
 650 @param[in] emf_uri
 651     New EMF URI of \bt_p{event_class} (copied).
 652
 653 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK
 654     Success.
 655 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR
 656     Out of memory.
 657
 658 @bt_pre_not_null{event_class}
 659 @bt_pre_hot{event_class}
 660 @bt_pre_not_null{emf_uri}
 661
 662 @sa bt_event_class_get_emf_uri() &mdash;
 663     Returns the EMF URI of an event class.
 664 */
 665 extern bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri(
 666                 bt_event_class *event_class, const char *emf_uri) __BT_NOEXCEPT;
 667
 668 /*!
 669 @brief
 670     Returns the Eclipse Modeling Framework (EMF) URI of the event
 671     class \bt_p{event_class}.
 672
 673 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 674
 675 If \bt_p{event_class} has no EMF URI, this function returns \c NULL.
 676
 677 @param[in] event_class
 678     Event class of which to get the EMF URI.
 679
 680 @returns
 681     @parblock
 682     EMF URI of \bt_p{event_class}, or \c NULL if none.
 683
 684     The returned pointer remains valid as long as \bt_p{event_class}
 685     is not modified.
 686     @endparblock
 687
 688 @bt_pre_not_null{event_class}
 689
 690 @sa bt_event_class_set_emf_uri() &mdash;
 691     Sets the EMF URI of an event class.
 692 */
 693 extern const char *bt_event_class_get_emf_uri(
 694                 const bt_event_class *event_class) __BT_NOEXCEPT;
 695
 696 /*!
 697 @brief
 698     Status codes for bt_event_class_set_payload_field_class() and
 699     bt_event_class_set_specific_context_field_class().
 700 */
 701 typedef enum bt_event_class_set_field_class_status {
 702         /*!
 703         @brief
 704             Success.
 705         */
 706         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK                = __BT_FUNC_STATUS_OK,
 707
 708         /*!
 709         @brief
 710             Out of memory.
 711         */
 712         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 713 } bt_event_class_set_field_class_status;
 714
 715 /*!
 716 @brief
 717     Sets the payload \bt_fc of the event class
 718     \bt_p{event_class} to \bt_p{field_class}.
 719
 720 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 721
 722 @param[in] event_class
 723     Event class of which to set the payload field class to
 724     \bt_p{field_class}.
 725 @param[in] field_class
 726     New payload field class of \bt_p{event_class}.
 727
 728 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
 729     Success.
 730 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
 731     Out of memory.
 732
 733 @bt_pre_not_null{event_class}
 734 @bt_pre_hot{event_class}
 735 @bt_pre_not_null{field_class}
 736 @bt_pre_is_struct_fc{field_class}
 737 @pre
 738     \bt_p{field_class}, or any of its contained field classes,
 739     is not already part of a \bt_stream_cls or of an event class.
 740 @pre
 741     If any of the field classes recursively contained in
 742     \bt_p{field_class} has a
 743     \ref api-tir-fc-link "link to another field class", it must honor
 744     the field class link rules.
 745
 746 @bt_post_success_frozen{field_class}
 747
 748 @sa bt_event_class_borrow_payload_field_class() &mdash;
 749     Borrows the payload field class of an event class.
 750 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 751     Borrows the payload field class of an event class
 752     (\c const version).
 753 */
 754 extern bt_event_class_set_field_class_status
 755 bt_event_class_set_payload_field_class(bt_event_class *event_class,
 756                 bt_field_class *field_class) __BT_NOEXCEPT;
 757
 758 /*!
 759 @brief
 760     Borrows the payload \bt_fc from the event class \bt_p{event_class}.
 761
 762 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 763
 764 If \bt_p{event_class} has no payload field class, this function
 765 returns \c NULL.
 766
 767 @param[in] event_class
 768     Event class from which to borrow the payload field class.
 769
 770 @returns
 771     \em Borrowed reference of the payload field class of
 772     \bt_p{event_class}, or \c NULL if none.
 773
 774 @bt_pre_not_null{event_class}
 775
 776 @sa bt_event_class_set_payload_field_class() &mdash;
 777     Sets the payload field class of an event class.
 778 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 779     \c const version of this function.
 780 */
 781 extern bt_field_class *bt_event_class_borrow_payload_field_class(
 782                 bt_event_class *event_class) __BT_NOEXCEPT;
 783
 784 /*!
 785 @brief
 786     Borrows the payload \bt_fc from the event class \bt_p{event_class}
 787     (\c const version).
 788
 789 See bt_event_class_borrow_payload_field_class().
 790 */
 791 extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
 792                 const bt_event_class *event_class) __BT_NOEXCEPT;
 793
 794 /*!
 795 @brief
 796     Sets the specific context \bt_fc of the event class
 797     \bt_p{event_class} to \bt_p{field_class}.
 798
 799 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
 800 property.
 801
 802 @param[in] event_class
 803     Event class of which to set the specific context field class to
 804     \bt_p{field_class}.
 805 @param[in] field_class
 806     New specific context field class of \bt_p{event_class}.
 807
 808 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
 809     Success.
 810 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
 811     Out of memory.
 812
 813 @bt_pre_not_null{event_class}
 814 @bt_pre_hot{event_class}
 815 @bt_pre_not_null{field_class}
 816 @bt_pre_is_struct_fc{field_class}
 817 @pre
 818     \bt_p{field_class}, or any of its contained field classes,
 819     is not already part of a \bt_stream_cls or of an event class.
 820 @pre
 821     If any of the field classes recursively contained in
 822     \bt_p{field_class} has a
 823     \ref api-tir-fc-link "link to another field class", it must honor
 824     the field class link rules.
 825
 826 @bt_post_success_frozen{field_class}
 827
 828 @sa bt_event_class_borrow_specific_context_field_class() &mdash;
 829     Borrows the specific context field class of an event class.
 830 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
 831     Borrows the specific context field class of an event class
 832     (\c const version).
 833 */
 834 extern bt_event_class_set_field_class_status
 835 bt_event_class_set_specific_context_field_class(bt_event_class *event_class,
 836                 bt_field_class *field_class) __BT_NOEXCEPT;
 837
 838 /*!
 839 @brief
 840     Borrows the specific context \bt_fc from the event class
 841     \bt_p{event_class}.
 842
 843 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
 844 property.
 845
 846 If \bt_p{event_class} has no specific context field class, this function
 847 returns \c NULL.
 848
 849 @param[in] event_class
 850     Event class from which to borrow the specific context field class.
 851
 852 @returns
 853     \em Borrowed reference of the specific context field class of
 854     \bt_p{event_class}, or \c NULL if none.
 855
 856 @bt_pre_not_null{event_class}
 857
 858 @sa bt_event_class_set_specific_context_field_class() &mdash;
 859     Sets the specific context field class of an event class.
 860 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
 861     \c const version of this function.
 862 */
 863 extern bt_field_class *
 864 bt_event_class_borrow_specific_context_field_class(
 865                 bt_event_class *event_class) __BT_NOEXCEPT;
 866
 867 /*!
 868 @brief
 869     Borrows the specific context \bt_fc from the event class
 870     \bt_p{event_class} (\c const version).
 871
 872 See bt_event_class_borrow_specific_context_field_class().
 873 */
 874 extern const bt_field_class *
 875 bt_event_class_borrow_specific_context_field_class_const(
 876                 const bt_event_class *event_class) __BT_NOEXCEPT;
 877
 878 /*!
 879 @brief
 880     Sets the user attributes of the event class \bt_p{event_class} to
 881     \bt_p{user_attributes}.
 882
 883 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
 884
 885 @note
 886     When you create a default event class with bt_event_class_create()
 887     or bt_event_class_create_with_id(), the event class's initial user
 888     attributes is an empty \bt_map_val. Therefore you can borrow it with
 889     bt_event_class_borrow_user_attributes() and fill it directly instead
 890     of setting a new one with this function.
 891
 892 @param[in] event_class
 893     Event class of which to set the user attributes to
 894     \bt_p{user_attributes}.
 895 @param[in] user_attributes
 896     New user attributes of \bt_p{event_class}.
 897
 898 @bt_pre_not_null{event_class}
 899 @bt_pre_hot{event_class}
 900 @bt_pre_not_null{user_attributes}
 901 @bt_pre_is_map_val{user_attributes}
 902
 903 @sa bt_event_class_borrow_user_attributes() &mdash;
 904     Borrows the user attributes of an event class.
 905 */
 906 extern void bt_event_class_set_user_attributes(
 907                 bt_event_class *event_class, const bt_value *user_attributes)
 908                 __BT_NOEXCEPT;
 909
 910 /*!
 911 @brief
 912     Borrows the user attributes of the event class \bt_p{event_class}.
 913
 914 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
 915
 916 @note
 917     When you create a default event class with bt_event_class_create()
 918     or bt_event_class_create_with_id(), the event class's initial user
 919     attributes is an empty \bt_map_val.
 920
 921 @param[in] event_class
 922     Event class from which to borrow the user attributes.
 923
 924 @returns
 925     User attributes of \bt_p{event_class} (a \bt_map_val).
 926
 927 @bt_pre_not_null{event_class}
 928
 929 @sa bt_event_class_set_user_attributes() &mdash;
 930     Sets the user attributes of an event class.
 931 @sa bt_event_class_borrow_user_attributes_const() &mdash;
 932     \c const version of this function.
 933 */
 934 extern bt_value *bt_event_class_borrow_user_attributes(
 935                 bt_event_class *event_class) __BT_NOEXCEPT;
 936
 937 /*!
 938 @brief
 939     Borrows the user attributes of the event class \bt_p{event_class}
 940     (\c const version).
 941
 942 See bt_event_class_borrow_user_attributes().
 943 */
 944 extern const bt_value *bt_event_class_borrow_user_attributes_const(
 945                 const bt_event_class *event_class) __BT_NOEXCEPT;
 946
 947 /*! @} */
 948
 949 /*!
 950 @name Reference count
 951 @{
 952 */
 953
 954 /*!
 955 @brief
 956     Increments the \ref api-fund-shared-object "reference count" of
 957     the event class \bt_p{event_class}.
 958
 959 @param[in] event_class
 960     @parblock
 961     Event class of which to increment the reference count.
 962
 963     Can be \c NULL.
 964     @endparblock
 965
 966 @sa bt_event_class_put_ref() &mdash;
 967     Decrements the reference count of an event class.
 968 */
 969 extern void bt_event_class_get_ref(
 970                 const bt_event_class *event_class) __BT_NOEXCEPT;
 971
 972 /*!
 973 @brief
 974     Decrements the \ref api-fund-shared-object "reference count" of
 975     the event class \bt_p{event_class}.
 976
 977 @param[in] event_class
 978     @parblock
 979     Event class of which to decrement the reference count.
 980
 981     Can be \c NULL.
 982     @endparblock
 983
 984 @sa bt_event_class_get_ref() &mdash;
 985     Increments the reference count of an event class.
 986 */
 987 extern void bt_event_class_put_ref(
 988                 const bt_event_class *event_class) __BT_NOEXCEPT;
 989
 990 /*!
 991 @brief
 992     Decrements the reference count of the event class
 993     \bt_p{_event_class}, and then sets \bt_p{_event_class} to \c NULL.
 994
 995 @param _event_class
 996     @parblock
 997     Event class of which to decrement the reference count.
 998
 999     Can contain \c NULL.
1000     @endparblock
1001
1002 @bt_pre_assign_expr{_event_class}
1003 */
1004 #define BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class)  \
1005         do {                                            \
1006                 bt_event_class_put_ref(_event_class);   \
1007                 (_event_class) = NULL;                  \
1008         } while (0)
1009
1010 /*!
1011 @brief
1012     Decrements the reference count of the event class \bt_p{_dst}, sets
1013     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1014
1015 This macro effectively moves an event class reference from the expression
1016 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1017 \bt_p{_dst} reference.
1018
1019 @param _dst
1020     @parblock
1021     Destination expression.
1022
1023     Can contain \c NULL.
1024     @endparblock
1025 @param _src
1026     @parblock
1027     Source expression.
1028
1029     Can contain \c NULL.
1030     @endparblock
1031
1032 @bt_pre_assign_expr{_dst}
1033 @bt_pre_assign_expr{_src}
1034 */
1035 #define BT_EVENT_CLASS_MOVE_REF(_dst, _src)     \
1036         do {                                    \
1037                 bt_event_class_put_ref(_dst);   \
1038                 (_dst) = (_src);                \
1039                 (_src) = NULL;                  \
1040         } while (0)
1041
1042 /*! @} */
1043
1044 /*! @} */
1045
1046 #ifdef __cplusplus
1047 }
1048 #endif
1049
1050 #endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_H */