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