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

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