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>
 103     \anchor api-tir-ev-cls-prop-ns
 104     \bt_dt_opt Namespace
 105     (only available when the parent \bt_trace_cls was created
 106     from a \bt_comp which belongs to a trace processing \bt_graph
 107     with the effective \bt_mip version&nbsp;1)
 108   </dt>
 109   <dd>
 110     Namespace of the event class.
 111
 112     Use bt_event_class_set_namespace() and
 113     bt_event_class_get_namespace().
 114   </dd>
 115
 116   <dt>\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name</dt>
 117   <dd>
 118     Name of the event class.
 119
 120     Use bt_event_class_set_name() and bt_event_class_get_name().
 121   </dd>
 122
 123   <dt>
 124     \anchor api-tir-ev-cls-prop-uid
 125     \bt_dt_opt UID
 126     (only available when the parent \bt_trace_cls was created
 127     from a \bt_comp which belongs to a trace processing \bt_graph
 128     with the effective \bt_mip version&nbsp;1)
 129   </dt>
 130   <dd>
 131     <a href="https://en.wikipedia.org/wiki/Unique_identifier">Unique identifier</a>
 132     (UID) of the event class.
 133
 134     Use bt_event_class_set_uid() and
 135     bt_event_class_get_uid().
 136   </dd>
 137
 138   <dt>\anchor api-tir-ev-cls-prop-log-lvl \bt_dt_opt Log level</dt>
 139   <dd>
 140     Log level of the event class.
 141
 142     The event class's log level corresponds to the log level of the
 143     tracer's original instrumentation point.
 144
 145     Use bt_event_class_set_log_level() and
 146     bt_event_class_get_log_level().
 147   </dd>
 148
 149   <dt>
 150     \anchor api-tir-ev-cls-prop-emf-uri
 151     \bt_dt_opt Eclipse Modeling Framework (EMF) URI
 152   </dt>
 153   <dd>
 154     EMF URI of the event class.
 155
 156     Use bt_event_class_set_emf_uri() and
 157     bt_event_class_get_emf_uri().
 158   </dd>
 159
 160   <dt>
 161     \anchor api-tir-ev-cls-prop-p-fc
 162     \bt_dt_opt Payload field class
 163   </dt>
 164   <dd>
 165     Payload \bt_fc of the event class.
 166
 167     The payload of an event class instance (\bt_ev) contains the
 168     event's main data.
 169
 170     Use bt_event_class_set_payload_field_class()
 171     bt_event_class_borrow_payload_field_class(),
 172     and bt_event_class_borrow_payload_field_class_const().
 173   </dd>
 174
 175   <dt>
 176     \anchor api-tir-ev-cls-prop-sc-fc
 177     \bt_dt_opt Specific context field class
 178   </dt>
 179   <dd>
 180     Specific context \bt_fc of the event class.
 181
 182     The specific context of an event class instance (\bt_ev) contains
 183     any contextual data of which the layout is specific to the
 184     event's class and which does not belong to the payload.
 185
 186     Use bt_event_class_set_specific_context_field_class()
 187     bt_event_class_borrow_specific_context_field_class(),
 188     and bt_event_class_borrow_specific_context_field_class_const().
 189   </dd>
 190
 191   <dt>
 192     \anchor api-tir-ev-cls-prop-user-attrs
 193     \bt_dt_opt User attributes
 194   </dt>
 195   <dd>
 196     User attributes of the event class.
 197
 198     User attributes are custom attributes attached to an event class.
 199
 200     Use bt_event_class_set_user_attributes(),
 201     bt_event_class_borrow_user_attributes(), and
 202     bt_event_class_borrow_user_attributes_const().
 203   </dd>
 204 </dl>
 205 */
 206
 207 /*! @{ */
 208
 209 /*!
 210 @name Type
 211 @{
 212
 213 @typedef struct bt_event_class bt_event_class;
 214
 215 @brief
 216     Event class.
 217
 218 @}
 219 */
 220
 221 /*!
 222 @name Creation
 223 @{
 224 */
 225
 226 /*!
 227 @brief
 228     Creates a default event class and adds it to the \bt_stream_cls
 229     \bt_p{stream_class}.
 230
 231 @attention
 232     @parblock
 233     Only use this function if
 234
 235     @code
 236     bt_stream_class_assigns_automatic_event_class_id(stream_class)
 237     @endcode
 238
 239     returns #BT_TRUE.
 240
 241     Otherwise, use bt_event_class_create_with_id().
 242     @endparblock
 243
 244 On success, the returned event class has the following property values:
 245
 246 <table>
 247   <tr>
 248     <th>Property
 249     <th>Value
 250   <tr>
 251     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
 252     <td>Automatically assigned by \bt_p{stream_class}
 253   <tr>
 254     <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-ns "namespace"
 255     <td>\em None
 256   <tr>
 257     <td>\ref api-tir-ev-cls-prop-name "Name"
 258     <td>\em None
 259   <tr>
 260     <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-uid "UID"
 261     <td>\em None
 262   <tr>
 263     <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
 264     <td>\em None
 265   <tr>
 266     <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
 267     <td>\em None
 268   <tr>
 269     <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
 270     <td>\em None
 271   <tr>
 272     <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
 273     <td>\em None
 274   <tr>
 275     <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
 276     <td>Empty \bt_map_val
 277 </table>
 278
 279 @param[in] stream_class
 280     Stream class to add the created event class to.
 281
 282 @returns
 283     New event class reference, or \c NULL on memory error.
 284
 285 @bt_pre_not_null{stream_class}
 286 @pre
 287     <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
 288     returns #BT_TRUE.
 289
 290 @bt_post_success_frozen{stream_class}
 291
 292 @sa bt_event_class_create_with_id() &mdash;
 293     Creates an event class with a specific numeric ID and adds it to a
 294     stream class.
 295 */
 296 extern bt_event_class *bt_event_class_create(
 297                 bt_stream_class *stream_class) __BT_NOEXCEPT;
 298
 299 /*!
 300 @brief
 301     Creates a default event class with the numeric ID \bt_p{id} and adds
 302     it to the \bt_stream_cls \bt_p{stream_class}.
 303
 304 @attention
 305     @parblock
 306     Only use this function if
 307
 308     @code
 309     bt_stream_class_assigns_automatic_event_class_id(stream_class)
 310     @endcode
 311
 312     returns #BT_FALSE.
 313
 314     Otherwise, use bt_event_class_create().
 315     @endparblock
 316
 317 On success, the returned event class has the following property values:
 318
 319 <table>
 320   <tr>
 321     <th>Property
 322     <th>Value
 323   <tr>
 324     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
 325     <td>\bt_p{id}
 326   <tr>
 327     <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-ns "namespace"
 328     <td>\em None
 329   <tr>
 330     <td>\ref api-tir-ev-cls-prop-name "Name"
 331     <td>\em None
 332   <tr>
 333     <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-uid "UID"
 334     <td>\em None
 335   <tr>
 336     <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
 337     <td>\em None
 338   <tr>
 339     <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
 340     <td>\em None
 341   <tr>
 342     <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
 343     <td>\em None
 344   <tr>
 345     <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
 346     <td>\em None
 347   <tr>
 348     <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
 349     <td>Empty \bt_map_val
 350 </table>
 351
 352 @param[in] stream_class
 353     Stream class to add the created event class to.
 354 @param[in] id
 355     Numeric ID of the event class to create and add to
 356     \bt_p{stream_class}.
 357
 358 @returns
 359     New event class reference, or \c NULL on memory error.
 360
 361 @bt_pre_not_null{stream_class}
 362 @pre
 363     <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
 364     returns #BT_FALSE.
 365 @pre
 366     \bt_p{stream_class} does not contain an event class with the numeric
 367     ID \bt_p{id}.
 368
 369 @bt_post_success_frozen{stream_class}
 370
 371 @sa bt_event_class_create() &mdash;
 372     Creates an event class with an automatic numeric ID and adds it to a
 373     stream class.
 374 */
 375 extern bt_event_class *bt_event_class_create_with_id(
 376                 bt_stream_class *stream_class, uint64_t id) __BT_NOEXCEPT;
 377
 378 /*! @} */
 379
 380 /*!
 381 @name Stream class access
 382 @{
 383 */
 384
 385 /*!
 386 @brief
 387     Borrows the \bt_stream_cls which contains the event class
 388     \bt_p{event_class}.
 389
 390 @param[in] event_class
 391     Event class from which to borrow the stream class which contains it.
 392
 393 @returns
 394     Stream class which contains \bt_p{event_class}.
 395
 396 @bt_pre_not_null{event_class}
 397
 398 @sa bt_event_class_borrow_stream_class_const() &mdash;
 399     \c const version of this function.
 400 */
 401 extern bt_stream_class *bt_event_class_borrow_stream_class(
 402                 bt_event_class *event_class) __BT_NOEXCEPT;
 403
 404 /*!
 405 @brief
 406     Borrows the \bt_stream_cls which contains the event class
 407     \bt_p{event_class} (\c const version).
 408
 409 See bt_event_class_borrow_stream_class().
 410 */
 411 extern const bt_stream_class *bt_event_class_borrow_stream_class_const(
 412                 const bt_event_class *event_class) __BT_NOEXCEPT;
 413
 414 /*! @} */
 415
 416 /*!
 417 @name Properties
 418 @{
 419 */
 420
 421 /*!
 422 @brief
 423     Returns the numeric ID of the event class \bt_p{event_class}.
 424
 425 See the \ref api-tir-ev-cls-prop-id "numeric ID" property.
 426
 427 @param[in] event_class
 428     Event class of which to get the numeric ID.
 429
 430 @returns
 431     Numeric ID of \bt_p{event_class}.
 432
 433 @bt_pre_not_null{event_class}
 434
 435 @sa bt_event_class_create_with_id() &mdash;
 436     Creates an event class with a specific numeric ID and adds it to a
 437     stream class.
 438 */
 439 extern uint64_t bt_event_class_get_id(
 440                 const bt_event_class *event_class) __BT_NOEXCEPT;
 441
 442 /*!
 443 @brief
 444     Status codes for bt_event_class_set_namespace().
 445 */
 446 typedef enum bt_event_class_set_namespace_status {
 447         /*!
 448         @brief
 449             Success.
 450         */
 451         BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 452
 453         /*!
 454         @brief
 455             Out of memory.
 456         */
 457         BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
 458 } bt_event_class_set_namespace_status;
 459
 460 /*!
 461 @brief
 462     Sets the namespace of the event class \bt_p{event_class} to
 463     a copy of \bt_p{ns}.
 464
 465 See the \ref api-tir-ev-cls-prop-ns "namespace" property.
 466
 467 @param[in] event_class
 468     Event class of which to set the namespace to \bt_p{ns}.
 469 @param[in] name
 470     New namespace of \bt_p{event_class} (copied).
 471
 472 @retval #BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK
 473     Success.
 474 @retval #BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR
 475     Out of memory.
 476
 477 @bt_pre_not_null{event_class}
 478 @bt_pre_hot{event_class}
 479 @bt_pre_ev_cls_with_mip{event_class, 1}
 480 @bt_pre_not_null{ns}
 481
 482 @sa bt_event_class_get_namespace() &mdash;
 483     Returns the namespace of an event class.
 484 */
 485 extern bt_event_class_set_namespace_status bt_event_class_set_namespace(
 486                 bt_event_class *event_class, const char *ns) __BT_NOEXCEPT;
 487
 488 /*!
 489 @brief
 490     Returns the namespace of the event class \bt_p{event_class}.
 491
 492 See the \ref api-tir-ev-cls-prop-ns "namespace" property.
 493
 494 If \bt_p{event_class} has no namespace, this function returns \c NULL.
 495
 496 @param[in] event_class
 497     Event class of which to get the namespace.
 498
 499 @returns
 500     @parblock
 501     Namespace of \bt_p{event_class}, or \c NULL if none.
 502
 503     The returned pointer remains valid as long as \bt_p{event_class}
 504     is not modified.
 505     @endparblock
 506
 507 @bt_pre_not_null{event_class}
 508 @bt_pre_ev_cls_with_mip{event_class, 1}
 509
 510 @sa bt_event_class_set_namespace() &mdash;
 511     Sets the namespace of a event class.
 512 */
 513 extern const char *
 514 bt_event_class_get_namespace(const bt_event_class *event_class) __BT_NOEXCEPT;
 515
 516 /*!
 517 @brief
 518     Status codes for bt_event_class_set_name().
 519 */
 520 typedef enum bt_event_class_set_name_status {
 521         /*!
 522         @brief
 523             Success.
 524         */
 525         BT_EVENT_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
 526
 527         /*!
 528         @brief
 529             Out of memory.
 530         */
 531         BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 532 } bt_event_class_set_name_status;
 533
 534 /*!
 535 @brief
 536     Sets the name of the event class \bt_p{event_class} to
 537     a copy of \bt_p{name}.
 538
 539 See the \ref api-tir-ev-cls-prop-name "name" property.
 540
 541 @param[in] event_class
 542     Event class of which to set the name to \bt_p{name}.
 543 @param[in] name
 544     New name of \bt_p{event_class} (copied).
 545
 546 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_OK
 547     Success.
 548 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 549     Out of memory.
 550
 551 @bt_pre_not_null{event_class}
 552 @bt_pre_hot{event_class}
 553 @bt_pre_not_null{name}
 554
 555 @sa bt_event_class_get_name() &mdash;
 556     Returns the name of an event class.
 557 */
 558 extern bt_event_class_set_name_status bt_event_class_set_name(
 559                 bt_event_class *event_class, const char *name) __BT_NOEXCEPT;
 560
 561 /*!
 562 @brief
 563     Status codes for bt_event_class_set_uid().
 564 */
 565 typedef enum bt_event_class_set_uid_status {
 566         /*!
 567         @brief
 568             Success.
 569         */
 570         BT_EVENT_CLASS_SET_UID_STATUS_OK                = __BT_FUNC_STATUS_OK,
 571
 572         /*!
 573         @brief
 574             Out of memory.
 575         */
 576         BT_EVENT_CLASS_SET_UID_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 577 } bt_event_class_set_uid_status;
 578
 579 /*!
 580 @brief
 581     Sets the
 582     <a href="https://en.wikipedia.org/wiki/Unique_identifier">unique identifier</a> (UID)
 583     of the stream class \bt_p{event_class} to
 584     a copy of \bt_p{uid}.
 585
 586 See the \ref api-tir-ev-cls-prop-uid "UID" property.
 587
 588 @param[in] event_class
 589     Event class of which to set the UID to \bt_p{uid}.
 590 @param[in] name
 591     New UID of \bt_p{event_class} (copied).
 592
 593 @retval #BT_EVENT_CLASS_SET_UID_STATUS_OK
 594     Success.
 595 @retval #BT_EVENT_CLASS_SET_UID_STATUS_MEMORY_ERROR
 596     Out of memory.
 597
 598 @bt_pre_not_null{event_class}
 599 @bt_pre_hot{event_class}
 600 @bt_pre_ev_cls_with_mip{event_class, 1}
 601 @bt_pre_not_null{uid}
 602
 603 @sa bt_event_class_get_uid() &mdash;
 604     Returns the UID of an event class.
 605 */
 606 extern bt_event_class_set_uid_status bt_event_class_set_uid(
 607                 bt_event_class *event_class, const char *uid) __BT_NOEXCEPT;
 608
 609 /*!
 610 @brief
 611     Returns the UID of the event class \bt_p{event_class}.
 612
 613 See the \ref api-tir-ev-cls-prop-uid "UID" property.
 614
 615 If \bt_p{event_class} has no UID, this function returns \c NULL.
 616
 617 @param[in] event_class
 618     Event class of which to get the UID.
 619
 620 @returns
 621     @parblock
 622     UID of \bt_p{event_class}, or \c NULL if none.
 623
 624     The returned pointer remains valid as long as \bt_p{event_class}
 625     is not modified.
 626     @endparblock
 627
 628 @bt_pre_not_null{event_class}
 629 @bt_pre_ev_cls_with_mip{event_class, 1}
 630
 631 @sa bt_event_class_set_uid() &mdash;
 632     Sets the UID of an event class.
 633 */
 634 extern const char *
 635 bt_event_class_get_uid(const bt_event_class *event_class) __BT_NOEXCEPT;
 636
 637 /*!
 638 @brief
 639     Returns the name of the event class \bt_p{event_class}.
 640
 641 See the \ref api-tir-ev-cls-prop-name "name" property.
 642
 643 If \bt_p{event_class} has no name, this function returns \c NULL.
 644
 645 @param[in] event_class
 646     Event class of which to get the name.
 647
 648 @returns
 649     @parblock
 650     Name of \bt_p{event_class}, or \c NULL if none.
 651
 652     The returned pointer remains valid as long as \bt_p{event_class}
 653     is not modified.
 654     @endparblock
 655
 656 @bt_pre_not_null{event_class}
 657
 658 @sa bt_event_class_set_name() &mdash;
 659     Sets the name of an event class.
 660 */
 661 extern const char *bt_event_class_get_name(
 662                 const bt_event_class *event_class) __BT_NOEXCEPT;
 663
 664 /*!
 665 @brief
 666     Event class log level enumerators.
 667 */
 668 typedef enum bt_event_class_log_level {
 669         /*!
 670         @brief
 671             System is unusable.
 672         */
 673         BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY              = 0,
 674
 675         /*!
 676         @brief
 677             Action must be taken immediately.
 678         */
 679         BT_EVENT_CLASS_LOG_LEVEL_ALERT                  = 1,
 680
 681         /*!
 682         @brief
 683             Critical conditions.
 684         */
 685         BT_EVENT_CLASS_LOG_LEVEL_CRITICAL               = 2,
 686
 687         /*!
 688         @brief
 689             Error conditions.
 690         */
 691         BT_EVENT_CLASS_LOG_LEVEL_ERROR                  = 3,
 692
 693         /*!
 694         @brief
 695             Warning conditions.
 696         */
 697         BT_EVENT_CLASS_LOG_LEVEL_WARNING                = 4,
 698
 699         /*!
 700         @brief
 701             Normal, but significant, condition.
 702         */
 703         BT_EVENT_CLASS_LOG_LEVEL_NOTICE                 = 5,
 704
 705         /*!
 706         @brief
 707             Informational message.
 708         */
 709         BT_EVENT_CLASS_LOG_LEVEL_INFO                   = 6,
 710
 711         /*!
 712         @brief
 713             Debugging information with system-level scope
 714             (set of programs).
 715         */
 716         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM           = 7,
 717
 718         /*!
 719         @brief
 720             Debugging information with program-level scope
 721             (set of processes).
 722         */
 723         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM          = 8,
 724
 725         /*!
 726         @brief
 727             Debugging information with process-level scope
 728             (set of modules).
 729         */
 730         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS          = 9,
 731
 732         /*!
 733         @brief
 734             Debugging information with module (executable/library) scope
 735             (set of units).
 736         */
 737         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE           = 10,
 738
 739         /*!
 740         @brief
 741             Debugging information with compilation unit scope
 742             (set of functions).
 743         */
 744         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT             = 11,
 745
 746         /*!
 747         @brief
 748             Debugging information with function-level scope.
 749         */
 750         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION         = 12,
 751
 752         /*!
 753         @brief
 754             Debugging information with function-level scope.
 755         */
 756         BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE             = 13,
 757
 758         /*!
 759         @brief
 760             Debugging-level message.
 761         */
 762         BT_EVENT_CLASS_LOG_LEVEL_DEBUG                  = 14,
 763 } bt_event_class_log_level;
 764
 765 /*!
 766 @brief
 767     Sets the log level of the event class \bt_p{event_class} to
 768     \bt_p{log_level}.
 769
 770 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 771
 772 @param[in] event_class
 773     Event class of which to set the log level to \bt_p{log_level}.
 774 @param[in] log_level
 775     New log level of \bt_p{event_class}.
 776
 777 @bt_pre_not_null{event_class}
 778 @bt_pre_hot{event_class}
 779
 780 @sa bt_event_class_get_log_level() &mdash;
 781     Returns the log level of an event class.
 782 */
 783 extern void bt_event_class_set_log_level(bt_event_class *event_class,
 784                 bt_event_class_log_level log_level) __BT_NOEXCEPT;
 785
 786 /*!
 787 @brief
 788     Returns the log level of the event class \bt_p{event_class}.
 789
 790 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
 791
 792 @param[in] event_class
 793     Event class of which to get the log level.
 794 @param[out] log_level
 795     <strong>If this function returns
 796     #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*log_level} is
 797     the log level of \bt_p{event_class}.
 798
 799 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
 800     The log level of \bt_p{event_class} is available.
 801 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
 802     The log level of \bt_p{event_class} is not available.
 803
 804 @bt_pre_not_null{event_class}
 805 @bt_pre_not_null{log_level}
 806
 807 @sa bt_event_class_set_log_level() &mdash;
 808     Sets the log level of an event class.
 809 */
 810 extern bt_property_availability bt_event_class_get_log_level(
 811                 const bt_event_class *event_class,
 812                 bt_event_class_log_level *log_level) __BT_NOEXCEPT;
 813
 814 /*!
 815 @brief
 816     Status codes for bt_event_class_set_emf_uri().
 817 */
 818 typedef enum bt_event_class_set_emf_uri_status {
 819         /*!
 820         @brief
 821             Success.
 822         */
 823         BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK            = __BT_FUNC_STATUS_OK,
 824
 825         /*!
 826         @brief
 827             Out of memory.
 828         */
 829         BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 830 } bt_event_class_set_emf_uri_status;
 831
 832 /*!
 833 @brief
 834     Sets the Eclipse Modeling Framework (EMF) URI of the event class
 835     \bt_p{event_class} to a copy of \bt_p{emf_uri}.
 836
 837 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 838
 839 @param[in] event_class
 840     Event class of which to set the EMF URI to \bt_p{emf_uri}.
 841 @param[in] emf_uri
 842     New EMF URI of \bt_p{event_class} (copied).
 843
 844 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK
 845     Success.
 846 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR
 847     Out of memory.
 848
 849 @bt_pre_not_null{event_class}
 850 @bt_pre_hot{event_class}
 851 @bt_pre_not_null{emf_uri}
 852
 853 @sa bt_event_class_get_emf_uri() &mdash;
 854     Returns the EMF URI of an event class.
 855 */
 856 extern bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri(
 857                 bt_event_class *event_class, const char *emf_uri) __BT_NOEXCEPT;
 858
 859 /*!
 860 @brief
 861     Returns the Eclipse Modeling Framework (EMF) URI of the event
 862     class \bt_p{event_class}.
 863
 864 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
 865
 866 If \bt_p{event_class} has no EMF URI, this function returns \c NULL.
 867
 868 @param[in] event_class
 869     Event class of which to get the EMF URI.
 870
 871 @returns
 872     @parblock
 873     EMF URI of \bt_p{event_class}, or \c NULL if none.
 874
 875     The returned pointer remains valid as long as \bt_p{event_class}
 876     is not modified.
 877     @endparblock
 878
 879 @bt_pre_not_null{event_class}
 880
 881 @sa bt_event_class_set_emf_uri() &mdash;
 882     Sets the EMF URI of an event class.
 883 */
 884 extern const char *bt_event_class_get_emf_uri(
 885                 const bt_event_class *event_class) __BT_NOEXCEPT;
 886
 887 /*!
 888 @brief
 889     Status codes for bt_event_class_set_payload_field_class() and
 890     bt_event_class_set_specific_context_field_class().
 891 */
 892 typedef enum bt_event_class_set_field_class_status {
 893         /*!
 894         @brief
 895             Success.
 896         */
 897         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK                = __BT_FUNC_STATUS_OK,
 898
 899         /*!
 900         @brief
 901             Out of memory.
 902         */
 903         BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 904 } bt_event_class_set_field_class_status;
 905
 906 /*!
 907 @brief
 908     Sets the payload \bt_fc of the event class
 909     \bt_p{event_class} to \bt_p{field_class}.
 910
 911 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 912
 913 @param[in] event_class
 914     Event class of which to set the payload field class to
 915     \bt_p{field_class}.
 916 @param[in] field_class
 917     New payload field class of \bt_p{event_class}.
 918
 919 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
 920     Success.
 921 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
 922     Out of memory.
 923
 924 @bt_pre_not_null{event_class}
 925 @bt_pre_hot{event_class}
 926 @bt_pre_not_null{field_class}
 927 @bt_pre_is_struct_fc{field_class}
 928 @pre
 929     \bt_p{field_class}, or any of its contained field classes,
 930     is not already part of a \bt_stream_cls or of an event class.
 931 @pre
 932     If any of the field classes recursively contained in
 933     \bt_p{field_class} has a
 934     \ref api-tir-fc-link "link to another field class", it must honor
 935     the field class link rules.
 936
 937 @bt_post_success_frozen{field_class}
 938
 939 @sa bt_event_class_borrow_payload_field_class() &mdash;
 940     Borrows the payload field class of an event class.
 941 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 942     Borrows the payload field class of an event class
 943     (\c const version).
 944 */
 945 extern bt_event_class_set_field_class_status
 946 bt_event_class_set_payload_field_class(bt_event_class *event_class,
 947                 bt_field_class *field_class) __BT_NOEXCEPT;
 948
 949 /*!
 950 @brief
 951     Borrows the payload \bt_fc from the event class \bt_p{event_class}.
 952
 953 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
 954
 955 If \bt_p{event_class} has no payload field class, this function
 956 returns \c NULL.
 957
 958 @param[in] event_class
 959     Event class from which to borrow the payload field class.
 960
 961 @returns
 962     \em Borrowed reference of the payload field class of
 963     \bt_p{event_class}, or \c NULL if none.
 964
 965 @bt_pre_not_null{event_class}
 966
 967 @sa bt_event_class_set_payload_field_class() &mdash;
 968     Sets the payload field class of an event class.
 969 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
 970     \c const version of this function.
 971 */
 972 extern bt_field_class *bt_event_class_borrow_payload_field_class(
 973                 bt_event_class *event_class) __BT_NOEXCEPT;
 974
 975 /*!
 976 @brief
 977     Borrows the payload \bt_fc from the event class \bt_p{event_class}
 978     (\c const version).
 979
 980 See bt_event_class_borrow_payload_field_class().
 981 */
 982 extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
 983                 const bt_event_class *event_class) __BT_NOEXCEPT;
 984
 985 /*!
 986 @brief
 987     Sets the specific context \bt_fc of the event class
 988     \bt_p{event_class} to \bt_p{field_class}.
 989
 990 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
 991 property.
 992
 993 @param[in] event_class
 994     Event class of which to set the specific context field class to
 995     \bt_p{field_class}.
 996 @param[in] field_class
 997     New specific context field class of \bt_p{event_class}.
 998
 999 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
1000     Success.
1001 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1002     Out of memory.
1003
1004 @bt_pre_not_null{event_class}
1005 @bt_pre_hot{event_class}
1006 @bt_pre_not_null{field_class}
1007 @bt_pre_is_struct_fc{field_class}
1008 @pre
1009     \bt_p{field_class}, or any of its contained field classes,
1010     is not already part of a \bt_stream_cls or of an event class.
1011 @pre
1012     If any of the field classes recursively contained in
1013     \bt_p{field_class} has a
1014     \ref api-tir-fc-link "link to another field class", it must honor
1015     the field class link rules.
1016
1017 @bt_post_success_frozen{field_class}
1018
1019 @sa bt_event_class_borrow_specific_context_field_class() &mdash;
1020     Borrows the specific context field class of an event class.
1021 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
1022     Borrows the specific context field class of an event class
1023     (\c const version).
1024 */
1025 extern bt_event_class_set_field_class_status
1026 bt_event_class_set_specific_context_field_class(bt_event_class *event_class,
1027                 bt_field_class *field_class) __BT_NOEXCEPT;
1028
1029 /*!
1030 @brief
1031     Borrows the specific context \bt_fc from the event class
1032     \bt_p{event_class}.
1033
1034 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
1035 property.
1036
1037 If \bt_p{event_class} has no specific context field class, this function
1038 returns \c NULL.
1039
1040 @param[in] event_class
1041     Event class from which to borrow the specific context field class.
1042
1043 @returns
1044     \em Borrowed reference of the specific context field class of
1045     \bt_p{event_class}, or \c NULL if none.
1046
1047 @bt_pre_not_null{event_class}
1048
1049 @sa bt_event_class_set_specific_context_field_class() &mdash;
1050     Sets the specific context field class of an event class.
1051 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
1052     \c const version of this function.
1053 */
1054 extern bt_field_class *
1055 bt_event_class_borrow_specific_context_field_class(
1056                 bt_event_class *event_class) __BT_NOEXCEPT;
1057
1058 /*!
1059 @brief
1060     Borrows the specific context \bt_fc from the event class
1061     \bt_p{event_class} (\c const version).
1062
1063 See bt_event_class_borrow_specific_context_field_class().
1064 */
1065 extern const bt_field_class *
1066 bt_event_class_borrow_specific_context_field_class_const(
1067                 const bt_event_class *event_class) __BT_NOEXCEPT;
1068
1069 /*!
1070 @brief
1071     Sets the user attributes of the event class \bt_p{event_class} to
1072     \bt_p{user_attributes}.
1073
1074 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
1075
1076 @note
1077     When you create a default event class with bt_event_class_create()
1078     or bt_event_class_create_with_id(), the event class's initial user
1079     attributes is an empty \bt_map_val. Therefore you can borrow it with
1080     bt_event_class_borrow_user_attributes() and fill it directly instead
1081     of setting a new one with this function.
1082
1083 @param[in] event_class
1084     Event class of which to set the user attributes to
1085     \bt_p{user_attributes}.
1086 @param[in] user_attributes
1087     New user attributes of \bt_p{event_class}.
1088
1089 @bt_pre_not_null{event_class}
1090 @bt_pre_hot{event_class}
1091 @bt_pre_not_null{user_attributes}
1092 @bt_pre_is_map_val{user_attributes}
1093
1094 @sa bt_event_class_borrow_user_attributes() &mdash;
1095     Borrows the user attributes of an event class.
1096 */
1097 extern void bt_event_class_set_user_attributes(
1098                 bt_event_class *event_class, const bt_value *user_attributes)
1099                 __BT_NOEXCEPT;
1100
1101 /*!
1102 @brief
1103     Borrows the user attributes of the event class \bt_p{event_class}.
1104
1105 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
1106
1107 @note
1108     When you create a default event class with bt_event_class_create()
1109     or bt_event_class_create_with_id(), the event class's initial user
1110     attributes is an empty \bt_map_val.
1111
1112 @param[in] event_class
1113     Event class from which to borrow the user attributes.
1114
1115 @returns
1116     User attributes of \bt_p{event_class} (a \bt_map_val).
1117
1118 @bt_pre_not_null{event_class}
1119
1120 @sa bt_event_class_set_user_attributes() &mdash;
1121     Sets the user attributes of an event class.
1122 @sa bt_event_class_borrow_user_attributes_const() &mdash;
1123     \c const version of this function.
1124 */
1125 extern bt_value *bt_event_class_borrow_user_attributes(
1126                 bt_event_class *event_class) __BT_NOEXCEPT;
1127
1128 /*!
1129 @brief
1130     Borrows the user attributes of the event class \bt_p{event_class}
1131     (\c const version).
1132
1133 See bt_event_class_borrow_user_attributes().
1134 */
1135 extern const bt_value *bt_event_class_borrow_user_attributes_const(
1136                 const bt_event_class *event_class) __BT_NOEXCEPT;
1137
1138 /*! @} */
1139
1140 /*!
1141 @name Reference count
1142 @{
1143 */
1144
1145 /*!
1146 @brief
1147     Increments the \ref api-fund-shared-object "reference count" of
1148     the event class \bt_p{event_class}.
1149
1150 @param[in] event_class
1151     @parblock
1152     Event class of which to increment the reference count.
1153
1154     Can be \c NULL.
1155     @endparblock
1156
1157 @sa bt_event_class_put_ref() &mdash;
1158     Decrements the reference count of an event class.
1159 */
1160 extern void bt_event_class_get_ref(
1161                 const bt_event_class *event_class) __BT_NOEXCEPT;
1162
1163 /*!
1164 @brief
1165     Decrements the \ref api-fund-shared-object "reference count" of
1166     the event class \bt_p{event_class}.
1167
1168 @param[in] event_class
1169     @parblock
1170     Event class of which to decrement the reference count.
1171
1172     Can be \c NULL.
1173     @endparblock
1174
1175 @sa bt_event_class_get_ref() &mdash;
1176     Increments the reference count of an event class.
1177 */
1178 extern void bt_event_class_put_ref(
1179                 const bt_event_class *event_class) __BT_NOEXCEPT;
1180
1181 /*!
1182 @brief
1183     Decrements the reference count of the event class
1184     \bt_p{_event_class}, and then sets \bt_p{_event_class} to \c NULL.
1185
1186 @param _event_class
1187     @parblock
1188     Event class of which to decrement the reference count.
1189
1190     Can contain \c NULL.
1191     @endparblock
1192
1193 @bt_pre_assign_expr{_event_class}
1194 */
1195 #define BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class)  \
1196         do {                                            \
1197                 bt_event_class_put_ref(_event_class);   \
1198                 (_event_class) = NULL;                  \
1199         } while (0)
1200
1201 /*!
1202 @brief
1203     Decrements the reference count of the event class \bt_p{_dst}, sets
1204     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1205
1206 This macro effectively moves an event class reference from the expression
1207 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1208 \bt_p{_dst} reference.
1209
1210 @param _dst
1211     @parblock
1212     Destination expression.
1213
1214     Can contain \c NULL.
1215     @endparblock
1216 @param _src
1217     @parblock
1218     Source expression.
1219
1220     Can contain \c NULL.
1221     @endparblock
1222
1223 @bt_pre_assign_expr{_dst}
1224 @bt_pre_assign_expr{_src}
1225 */
1226 #define BT_EVENT_CLASS_MOVE_REF(_dst, _src)     \
1227         do {                                    \
1228                 bt_event_class_put_ref(_dst);   \
1229                 (_dst) = (_src);                \
1230                 (_src) = NULL;                  \
1231         } while (0)
1232
1233 /*! @} */
1234
1235 /*! @} */
1236
1237 #ifdef __cplusplus
1238 }
1239 #endif
1240
1241 #endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_H */