include/babeltrace2/trace-ir/trace.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_TRACE_H
   8 #define BABELTRACE2_TRACE_IR_TRACE_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-trace Trace
  26 @ingroup api-tir
  27
  28 @brief
  29     Trace (set of \bt_p_stream).
  30
  31 A <strong><em>trace</em></strong> is a set of \bt_p_stream with
  32 properties:
  33
  34 @image html trace-structure.png
  35
  36 In the illustration above, notice that a trace is an instance of a
  37 \bt_trace_cls and that it contains streams.
  38
  39 Borrow the class of a trace with bt_trace_borrow_class() and
  40 bt_trace_borrow_class_const().
  41
  42 A trace is a \ref api-tir "trace IR" data object.
  43
  44 A trace is a \ref api-fund-shared-object "shared object": get a
  45 new reference with bt_trace_get_ref() and put an existing
  46 reference with bt_trace_put_ref().
  47
  48 Some library functions \ref api-fund-freezing "freeze" traces on
  49 success. The documentation of those functions indicate this
  50 postcondition. With a frozen trace, you can still:
  51
  52 - Create \bt_p_stream from it with bt_stream_create() or
  53   bt_stream_create_with_id().
  54 - Add a destruction listener to it with
  55   bt_trace_add_destruction_listener().
  56
  57 The type of a trace is #bt_trace.
  58
  59 A trace contains \bt_p_stream. All the streams of a
  60 given trace have unique \ref api-tir-stream-prop-id "numeric IDs".
  61 Get the number of streams in a trace with bt_trace_get_stream_count().
  62 Borrow a specific stream from a trace with
  63 bt_trace_borrow_stream_by_index(),
  64 bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(),
  65 or bt_trace_borrow_stream_by_id_const().
  66
  67 Create a default trace from a \bt_trace_cls with bt_trace_create().
  68
  69 Add to and remove a destruction listener from a trace with
  70 bt_trace_add_destruction_listener() and
  71 bt_trace_remove_destruction_listener().
  72
  73 <h1>Properties</h1>
  74
  75 A trace has the following properties:
  76
  77 <dl>
  78   <dt>
  79     \anchor api-tir-trace-prop-name
  80     \bt_dt_opt Name
  81   </dt>
  82   <dd>
  83     Name of the trace.
  84
  85     Use bt_trace_set_name() and bt_trace_get_name().
  86   </dd>
  87
  88   <dt>
  89     \anchor api-tir-trace-prop-uuid
  90     \bt_dt_opt UUID
  91   </dt>
  92   <dd>
  93     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
  94     of the trace.
  95
  96     The trace's UUID uniquely identifies the trace.
  97
  98     Use bt_trace_set_uuid() and bt_trace_get_uuid().
  99   </dd>
 100
 101   <dt>
 102     \anchor api-tir-trace-prop-env
 103     \bt_dt_opt Environment
 104   </dt>
 105   <dd>
 106     Generic key-value store which describes the environment of the trace
 107     (for example, the system's hostname, its network address, the
 108     tracer's name and version, and the rest).
 109
 110     Trace environment keys are strings while values are signed integers
 111     or strings.
 112
 113     Set a trace environment entry's value with
 114     bt_trace_set_environment_entry_integer() and
 115     bt_trace_set_environment_entry_string().
 116
 117     Get the number of environment entries in a trace with
 118     bt_trace_get_environment_entry_count().
 119
 120     Borrow an environment entry from a trace with
 121     bt_trace_borrow_environment_entry_value_by_name_const().
 122   </dd>
 123
 124   <dt>
 125     \anchor api-tir-trace-prop-user-attrs
 126     \bt_dt_opt User attributes
 127   </dt>
 128   <dd>
 129     User attributes of the trace.
 130
 131     User attributes are custom attributes attached to a trace.
 132
 133     Use bt_trace_set_user_attributes(),
 134     bt_trace_borrow_user_attributes(), and
 135     bt_trace_borrow_user_attributes_const().
 136   </dd>
 137 </dl>
 138 */
 139
 140 /*! @{ */
 141
 142 /*!
 143 @name Type
 144 @{
 145
 146 @typedef struct bt_trace bt_trace;
 147
 148 @brief
 149     Trace.
 150
 151 @}
 152 */
 153
 154 /*!
 155 @name Creation
 156 @{
 157 */
 158
 159 /*!
 160 @brief
 161     Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
 162
 163 This function instantiates \bt_p{trace_class}.
 164
 165 On success, the returned trace has the following property values:
 166
 167 <table>
 168   <tr>
 169     <th>Property
 170     <th>Value
 171   <tr>
 172     <td>\ref api-tir-trace-prop-name "Name"
 173     <td>\em None
 174   <tr>
 175     <td>\ref api-tir-trace-prop-uuid "UUID"
 176     <td>\em None
 177   <tr>
 178     <td>\ref api-tir-trace-prop-env "Environment"
 179     <td>Empty
 180   <tr>
 181     <td>\ref api-tir-trace-prop-user-attrs "User attributes"
 182     <td>Empty \bt_map_val
 183 </table>
 184
 185 @param[in] trace_class
 186     Trace class from which to create the default trace.
 187
 188 @returns
 189     New trace reference, or \c NULL on memory error.
 190 */
 191 extern bt_trace *bt_trace_create(bt_trace_class *trace_class) __BT_NOEXCEPT;
 192
 193 /*! @} */
 194
 195 /*!
 196 @name Class access
 197 @{
 198 */
 199
 200 /*!
 201 @brief
 202     Borrows the \ref api-tir-trace-cls "class" of the trace
 203     \bt_p{trace}.
 204
 205 @param[in] trace
 206     Trace of which to borrow the class.
 207
 208 @returns
 209     \em Borrowed reference of the class of \bt_p{trace}.
 210
 211 @bt_pre_not_null{trace}
 212
 213 @sa bt_trace_borrow_class_const() &mdash;
 214     \c const version of this function.
 215 */
 216 extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace) __BT_NOEXCEPT;
 217
 218 /*!
 219 @brief
 220     Borrows the \ref api-tir-trace-cls "class" of the trace
 221     \bt_p{trace} (\c const version).
 222
 223 See bt_trace_borrow_class().
 224 */
 225 extern const bt_trace_class *bt_trace_borrow_class_const(
 226                 const bt_trace *trace) __BT_NOEXCEPT;
 227
 228 /*! @} */
 229
 230 /*!
 231 @name Stream access
 232 @{
 233 */
 234
 235 /*!
 236 @brief
 237     Returns the number of \bt_p_stream contained in the trace
 238     \bt_p{trace}.
 239
 240 @param[in] trace
 241     Trace of which to get the number of contained streams.
 242
 243 @returns
 244     Number of contained streams in \bt_p{trace}.
 245
 246 @bt_pre_not_null{trace}
 247 */
 248 extern uint64_t bt_trace_get_stream_count(const bt_trace *trace) __BT_NOEXCEPT;
 249
 250 /*!
 251 @brief
 252     Borrows the \bt_stream at index \bt_p{index} from the
 253     trace \bt_p{trace}.
 254
 255 @param[in] trace
 256     Trace from which to borrow the stream at index
 257     \bt_p{index}.
 258 @param[in] index
 259     Index of the stream to borrow from \bt_p{trace}.
 260
 261 @returns
 262     @parblock
 263     \em Borrowed reference of the stream of
 264     \bt_p{trace} at index \bt_p{index}.
 265
 266     The returned pointer remains valid as long as \bt_p{trace}
 267     exists.
 268     @endparblock
 269
 270 @bt_pre_not_null{trace}
 271 @pre
 272     \bt_p{index} is less than the number of streams in
 273     \bt_p{trace} (as returned by
 274     bt_trace_get_stream_count()).
 275
 276 @sa bt_trace_get_stream_count() &mdash;
 277     Returns the number of streams contained in a trace.
 278 @sa bt_trace_borrow_stream_by_index_const() &mdash;
 279     \c const version of this function.
 280 */
 281 extern bt_stream *bt_trace_borrow_stream_by_index(bt_trace *trace,
 282                 uint64_t index) __BT_NOEXCEPT;
 283
 284 /*!
 285 @brief
 286     Borrows the \bt_stream at index \bt_p{index} from the
 287     trace \bt_p{trace} (\c const version).
 288
 289 See bt_trace_borrow_stream_by_index().
 290 */
 291 extern const bt_stream *bt_trace_borrow_stream_by_index_const(
 292                 const bt_trace *trace, uint64_t index) __BT_NOEXCEPT;
 293
 294 /*!
 295 @brief
 296     Borrows the \bt_stream having the numeric ID \bt_p{id} from the
 297     trace \bt_p{trace}.
 298
 299 If there's no stream having the numeric ID \bt_p{id} in
 300 \bt_p{trace}, this function returns \c NULL.
 301
 302 @param[in] trace
 303     Trace from which to borrow the stream having the
 304     numeric ID \bt_p{id}.
 305 @param[in] id
 306     ID of the stream to borrow from \bt_p{trace}.
 307
 308 @returns
 309     @parblock
 310     \em Borrowed reference of the stream of
 311     \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
 312     if none.
 313
 314     The returned pointer remains valid as long as \bt_p{trace}
 315     exists.
 316     @endparblock
 317
 318 @bt_pre_not_null{trace}
 319
 320 @sa bt_trace_borrow_stream_by_id_const() &mdash;
 321     \c const version of this function.
 322 */
 323 extern bt_stream *bt_trace_borrow_stream_by_id(bt_trace *trace,
 324                 uint64_t id) __BT_NOEXCEPT;
 325
 326 /*!
 327 @brief
 328     Borrows the \bt_stream having the numeric ID \bt_p{id} from the
 329     trace \bt_p{trace} (\c const version).
 330
 331 See bt_trace_borrow_stream_by_id().
 332 */
 333 extern const bt_stream *bt_trace_borrow_stream_by_id_const(
 334                 const bt_trace *trace, uint64_t id) __BT_NOEXCEPT;
 335
 336 /*! @} */
 337
 338 /*!
 339 @name Properties
 340 @{
 341 */
 342
 343 /*!
 344 @brief
 345     Status codes for bt_trace_set_name().
 346 */
 347 typedef enum bt_trace_set_name_status {
 348         /*!
 349         @brief
 350             Success.
 351         */
 352         BT_TRACE_SET_NAME_STATUS_OK             = __BT_FUNC_STATUS_OK,
 353
 354         /*!
 355         @brief
 356             Out of memory.
 357         */
 358         BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 359 } bt_trace_set_name_status;
 360
 361 /*!
 362 @brief
 363     Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
 364
 365 See the \ref api-tir-trace-prop-name "name" property.
 366
 367 @param[in] trace
 368     Trace of which to set the name to \bt_p{name}.
 369 @param[in] name
 370     New name of \bt_p{trace} (copied).
 371
 372 @retval #BT_TRACE_SET_NAME_STATUS_OK
 373     Success.
 374 @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
 375     Out of memory.
 376
 377 @bt_pre_not_null{trace}
 378 @bt_pre_hot{trace}
 379 @bt_pre_not_null{name}
 380
 381 @sa bt_trace_get_name() &mdash;
 382     Returns the name of a trace.
 383 */
 384 extern bt_trace_set_name_status bt_trace_set_name(bt_trace *trace,
 385                 const char *name) __BT_NOEXCEPT;
 386
 387 /*!
 388 @brief
 389     Returns the name of the trace \bt_p{trace}.
 390
 391 See the \ref api-tir-trace-prop-name "name" property.
 392
 393 If \bt_p{trace} has no name, this function returns \c NULL.
 394
 395 @param[in] trace
 396     Trace of which to get the name.
 397
 398 @returns
 399     @parblock
 400     Name of \bt_p{trace}, or \c NULL if none.
 401
 402     The returned pointer remains valid as long as \bt_p{trace}
 403     is not modified.
 404     @endparblock
 405
 406 @bt_pre_not_null{trace}
 407
 408 @sa bt_trace_set_name() &mdash;
 409     Sets the name of a trace.
 410 */
 411 extern const char *bt_trace_get_name(const bt_trace *trace) __BT_NOEXCEPT;
 412
 413 /*!
 414 @brief
 415     Sets the
 416     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
 417     of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
 418
 419 See the \ref api-tir-trace-prop-uuid "UUID" property.
 420
 421 @param[in] trace
 422     Trace of which to set the UUID to \bt_p{uuid}.
 423 @param[in] uuid
 424     New UUID of \bt_p{trace} (copied).
 425
 426 @bt_pre_not_null{trace}
 427 @bt_pre_hot{trace}
 428 @bt_pre_not_null{uuid}
 429
 430 @sa bt_trace_get_uuid() &mdash;
 431     Returns the UUID of a trace.
 432 */
 433 extern void bt_trace_set_uuid(bt_trace *trace, bt_uuid uuid) __BT_NOEXCEPT;
 434
 435 /*!
 436 @brief
 437     Returns the UUID of the trace \bt_p{trace}.
 438
 439 See the \ref api-tir-trace-prop-uuid "UUID" property.
 440
 441 If \bt_p{trace} has no UUID, this function returns \c NULL.
 442
 443 @param[in] trace
 444     Trace of which to get the UUID.
 445
 446 @returns
 447     @parblock
 448     UUID of \bt_p{trace}, or \c NULL if none.
 449
 450     The returned pointer remains valid as long as \bt_p{trace}
 451     is not modified.
 452     @endparblock
 453
 454 @bt_pre_not_null{trace}
 455
 456 @sa bt_trace_set_uuid() &mdash;
 457     Sets the UUID of a trace.
 458 */
 459 extern bt_uuid bt_trace_get_uuid(const bt_trace *trace) __BT_NOEXCEPT;
 460
 461 /*!
 462 @brief
 463     Status codes for bt_trace_set_name().
 464 */
 465 typedef enum bt_trace_set_environment_entry_status {
 466         /*!
 467         @brief
 468             Success.
 469         */
 470         BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK                = __BT_FUNC_STATUS_OK,
 471
 472         /*!
 473         @brief
 474             Out of memory.
 475         */
 476         BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 477 } bt_trace_set_environment_entry_status;
 478
 479 /*!
 480 @brief
 481     Sets the value of the environment entry of the trace \bt_p{trace}
 482     named \bt_p{name} to the signed integer \bt_p{value}.
 483
 484 See the \ref api-tir-trace-prop-env "environment" property.
 485
 486 On success, if \bt_p{trace} already contains an environment entry named
 487 \bt_p{name}, this function replaces the existing entry's value with
 488 \bt_p{value}.
 489
 490 @param[in] trace
 491     Trace in which to insert or replace an environment entry named
 492     \bt_p{name} with the value \bt_p{value}.
 493 @param[in] name
 494     Name of the entry to insert or replace in \bt_p{trace} (copied).
 495 @param[in] value
 496     Value of the environment entry to insert or replace in \bt_p{trace}.
 497
 498 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
 499     Success.
 500 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
 501     Out of memory.
 502
 503 @bt_pre_not_null{trace}
 504 @bt_pre_hot{trace}
 505 @bt_pre_not_null{name}
 506
 507 @sa bt_trace_set_environment_entry_string() &mdash;
 508     Sets a trace environment entry's value to a string.
 509 */
 510 extern bt_trace_set_environment_entry_status
 511 bt_trace_set_environment_entry_integer(bt_trace *trace, const char *name,
 512                 int64_t value) __BT_NOEXCEPT;
 513
 514 /*!
 515 @brief
 516     Sets the value of the environment entry of the trace \bt_p{trace}
 517     named \bt_p{name} to the string \bt_p{value}.
 518
 519 See the \ref api-tir-trace-prop-env "environment" property.
 520
 521 On success, if \bt_p{trace} already contains an environment entry named
 522 \bt_p{name}, this function replaces the existing entry's value with
 523 \bt_p{value}.
 524
 525 @param[in] trace
 526     Trace in which to insert or replace an environment entry named
 527     \bt_p{name} with the value \bt_p{value}.
 528 @param[in] name
 529     Name of the entry to insert or replace in \bt_p{trace} (copied).
 530 @param[in] value
 531     Value of the environment entry to insert or replace in \bt_p{trace}.
 532
 533 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
 534     Success.
 535 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
 536     Out of memory.
 537
 538 @bt_pre_not_null{trace}
 539 @bt_pre_hot{trace}
 540 @bt_pre_not_null{name}
 541 @bt_pre_not_null{value}
 542
 543 @sa bt_trace_set_environment_entry_integer() &mdash;
 544     Sets a trace environment entry's value to a signed integer.
 545 */
 546 extern bt_trace_set_environment_entry_status
 547 bt_trace_set_environment_entry_string(bt_trace *trace, const char *name,
 548                 const char *value) __BT_NOEXCEPT;
 549
 550 /*!
 551 @brief
 552     Returns the number of environment entries contained in the trace
 553     \bt_p{trace}.
 554
 555 See the \ref api-tir-trace-prop-env "environment" property.
 556
 557 @param[in] trace
 558     Trace of which to get the number of environment entries.
 559
 560 @returns
 561     Number of environment entries in \bt_p{trace}.
 562
 563 @bt_pre_not_null{trace}
 564 */
 565 extern uint64_t bt_trace_get_environment_entry_count(
 566                 const bt_trace *trace) __BT_NOEXCEPT;
 567
 568 /*!
 569 @brief
 570     Borrows the environment entry at index \bt_p{index} from the
 571     trace \bt_p{trace}, setting \bt_p{*name} to its name and
 572     \bt_p{*value} to its value.
 573
 574 See the \ref api-tir-trace-prop-env "environment" property.
 575
 576 @param[in] trace
 577     Trace from which to borrow the environment entry at index
 578     \bt_p{index}.
 579 @param[in] index
 580     Index of the environment entry to borrow from \bt_p{trace}.
 581 @param[in] name
 582     @parblock
 583     <strong>On success</strong>, \bt_p{*name} is the name of the
 584     environment entry at index \bt_p{index} in \bt_p{trace}.
 585
 586     The returned pointer remains valid as long as \bt_p{trace}
 587     is not modified.
 588     @endparblock
 589 @param[in] value
 590     @parblock
 591     <strong>On success</strong>, \bt_p{*value} is a \em borrowed
 592     reference of the environment entry at index \bt_p{index} in
 593     \bt_p{trace}.
 594
 595     \bt_p{*value} is either a \bt_sint_val
 596     (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
 597     (#BT_VALUE_TYPE_STRING).
 598
 599     The returned pointer remains valid as long as \bt_p{trace}
 600     is not modified.
 601     @endparblock
 602
 603 @bt_pre_not_null{trace}
 604 @pre
 605     \bt_p{index} is less than the number of environment entries in
 606     \bt_p{trace} (as returned by
 607     bt_trace_get_environment_entry_count()).
 608 @bt_pre_not_null{name}
 609 @bt_pre_not_null{value}
 610
 611 @sa bt_trace_get_environment_entry_count() &mdash;
 612     Returns the number of environment entries contained in a trace.
 613 */
 614 extern void bt_trace_borrow_environment_entry_by_index_const(
 615                 const bt_trace *trace, uint64_t index,
 616                 const char **name, const bt_value **value) __BT_NOEXCEPT;
 617
 618 /*!
 619 @brief
 620     Borrows the value of the environment entry named \bt_p{name}
 621     in the trace \bt_p{trace}.
 622
 623 See the \ref api-tir-trace-prop-env "environment" property.
 624
 625 If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
 626 function returns \c NULL.
 627
 628 @param[in] trace
 629     Trace from which to borrow the value of the environment entry
 630     named \bt_p{name}.
 631 @param[in] name
 632     Name of the environment entry to borrow from \bt_p{trace}.
 633
 634 @returns
 635     @parblock
 636     \em Borrowed reference of the value of the environment entry named
 637     \bt_p{name} in \bt_p{trace}.
 638
 639     The returned value is either a \bt_sint_val
 640     (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
 641     (#BT_VALUE_TYPE_STRING).
 642
 643     The returned pointer remains valid as long as \bt_p{trace}
 644     is not modified.
 645     @endparblock
 646
 647 @bt_pre_not_null{trace}
 648 @bt_pre_not_null{name}
 649 */
 650 extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const(
 651                 const bt_trace *trace, const char *name) __BT_NOEXCEPT;
 652
 653 /*!
 654 @brief
 655     Sets the user attributes of the trace \bt_p{trace} to
 656     \bt_p{user_attributes}.
 657
 658 See the \ref api-tir-trace-prop-user-attrs "user attributes"
 659 property.
 660
 661 @note
 662     When you create a default trace with bt_trace_create(), the trace's
 663     initial user attributes is an empty \bt_map_val. Therefore you can
 664     borrow it with bt_trace_borrow_user_attributes() and fill it
 665     directly instead of setting a new one with this function.
 666
 667 @param[in] trace
 668     Trace of which to set the user attributes to \bt_p{user_attributes}.
 669 @param[in] user_attributes
 670     New user attributes of \bt_p{trace}.
 671
 672 @bt_pre_not_null{trace}
 673 @bt_pre_hot{trace}
 674 @bt_pre_not_null{user_attributes}
 675 @bt_pre_is_map_val{user_attributes}
 676
 677 @sa bt_trace_borrow_user_attributes() &mdash;
 678     Borrows the user attributes of a trace.
 679 */
 680 extern void bt_trace_set_user_attributes(
 681                 bt_trace *trace, const bt_value *user_attributes) __BT_NOEXCEPT;
 682
 683 /*!
 684 @brief
 685     Borrows the user attributes of the trace \bt_p{trace}.
 686
 687 See the \ref api-tir-trace-prop-user-attrs "user attributes"
 688 property.
 689
 690 @note
 691     When you create a default trace with bt_trace_create(), the trace's
 692     initial user attributes is an empty \bt_map_val.
 693
 694 @param[in] trace
 695     Trace from which to borrow the user attributes.
 696
 697 @returns
 698     User attributes of \bt_p{trace} (a \bt_map_val).
 699
 700 @bt_pre_not_null{trace}
 701
 702 @sa bt_trace_set_user_attributes() &mdash;
 703     Sets the user attributes of a trace.
 704 @sa bt_trace_borrow_user_attributes_const() &mdash;
 705     \c const version of this function.
 706 */
 707 extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace) __BT_NOEXCEPT;
 708
 709 /*!
 710 @brief
 711     Borrows the user attributes of the trace \bt_p{trace}
 712     (\c const version).
 713
 714 See bt_trace_borrow_user_attributes().
 715 */
 716 extern const bt_value *bt_trace_borrow_user_attributes_const(
 717                 const bt_trace *trace) __BT_NOEXCEPT;
 718
 719 /*! @} */
 720
 721 /*!
 722 @name Listeners
 723 @{
 724 */
 725
 726 /*!
 727 @brief
 728     User function for bt_trace_add_destruction_listener().
 729
 730 This is the user function type for a trace destruction listener.
 731
 732 @param[in] trace
 733     Trace being destroyed (\ref api-fund-freezing "frozen").
 734 @param[in] user_data
 735     User data, as passed as the \bt_p{user_data} parameter of
 736     bt_trace_add_destruction_listener().
 737
 738 @bt_pre_not_null{trace}
 739
 740 @post
 741     The reference count of \bt_p{trace} is not changed.
 742 @bt_post_no_error
 743
 744 @sa bt_trace_add_destruction_listener() &mdash;
 745     Adds a destruction listener to a trace.
 746 */
 747 typedef void (* bt_trace_destruction_listener_func)(
 748                 const bt_trace *trace, void *user_data);
 749
 750 /*!
 751 @brief
 752     Status codes for bt_trace_add_destruction_listener().
 753 */
 754 typedef enum bt_trace_add_listener_status {
 755         /*!
 756         @brief
 757             Success.
 758         */
 759         BT_TRACE_ADD_LISTENER_STATUS_OK                 = __BT_FUNC_STATUS_OK,
 760
 761         /*!
 762         @brief
 763             Out of memory.
 764         */
 765         BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
 766 } bt_trace_add_listener_status;
 767
 768 /*!
 769 @brief
 770     Adds a destruction listener having the function \bt_p{user_func}
 771     to the trace \bt_p{trace}.
 772
 773 All the destruction listener user functions of a trace are called
 774 when it's being destroyed.
 775
 776 If \bt_p{listener_id} is not \c NULL, then this function, on success,
 777 sets \bt_p{*listener_id} to the ID of the added destruction listener
 778 within \bt_p{trace}. You can then use this ID to remove the
 779 added destruction listener with bt_trace_remove_destruction_listener().
 780
 781 @param[in] trace
 782     Trace to add the destruction listener to.
 783 @param[in] user_func
 784     User function of the destruction listener to add to
 785     \bt_p{trace}.
 786 @param[in] user_data
 787     User data to pass as the \bt_p{user_data} parameter of
 788     \bt_p{user_func}.
 789 @param[out] listener_id
 790     <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
 791     is the ID of the added destruction listener within
 792     \bt_p{trace}.
 793
 794 @retval #BT_TRACE_ADD_LISTENER_STATUS_OK
 795     Success.
 796 @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
 797     Out of memory.
 798
 799 @bt_pre_not_null{trace}
 800 @bt_pre_not_null{user_func}
 801
 802 @sa bt_trace_remove_destruction_listener() &mdash;
 803     Removes a destruction listener from a trace.
 804 */
 805 extern bt_trace_add_listener_status bt_trace_add_destruction_listener(
 806                 const bt_trace *trace,
 807                 bt_trace_destruction_listener_func user_func,
 808                 void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT;
 809
 810 /*!
 811 @brief
 812     Status codes for bt_trace_remove_destruction_listener().
 813 */
 814 typedef enum bt_trace_remove_listener_status {
 815         /*!
 816         @brief
 817             Success.
 818         */
 819         BT_TRACE_REMOVE_LISTENER_STATUS_OK              = __BT_FUNC_STATUS_OK,
 820
 821         /*!
 822         @brief
 823             Out of memory.
 824         */
 825         BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 826 } bt_trace_remove_listener_status;
 827
 828 /*!
 829 @brief
 830     Removes the destruction listener having the ID \bt_p{listener_id}
 831     from the trace \bt_p{trace}.
 832
 833 The destruction listener to remove from \bt_p{trace} was
 834 previously added with bt_trace_add_destruction_listener().
 835
 836 You can call this function when \bt_p{trace} is
 837 \ref api-fund-freezing "frozen".
 838
 839 @param[in] trace
 840     Trace from which to remove the destruction listener having
 841     the ID \bt_p{listener_id}.
 842 @param[in] listener_id
 843     ID of the destruction listener to remove from \bt_p{trace}.
 844
 845 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
 846     Success.
 847 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
 848     Out of memory.
 849
 850 @bt_pre_not_null{trace}
 851 @pre
 852     \bt_p{listener_id} is the ID of an existing destruction listener
 853     in \bt_p{trace}.
 854
 855 @sa bt_trace_add_destruction_listener() &mdash;
 856     Adds a destruction listener to a trace.
 857 */
 858 extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener(
 859                 const bt_trace *trace, bt_listener_id listener_id)
 860                 __BT_NOEXCEPT;
 861
 862 /*! @} */
 863
 864 /*!
 865 @name Reference count
 866 @{
 867 */
 868
 869 /*!
 870 @brief
 871     Increments the \ref api-fund-shared-object "reference count" of
 872     the trace \bt_p{trace}.
 873
 874 @param[in] trace
 875     @parblock
 876     Trace of which to increment the reference count.
 877
 878     Can be \c NULL.
 879     @endparblock
 880
 881 @sa bt_trace_put_ref() &mdash;
 882     Decrements the reference count of a trace.
 883 */
 884 extern void bt_trace_get_ref(const bt_trace *trace) __BT_NOEXCEPT;
 885
 886 /*!
 887 @brief
 888     Decrements the \ref api-fund-shared-object "reference count" of
 889     the trace \bt_p{trace}.
 890
 891 @param[in] trace
 892     @parblock
 893     Trace of which to decrement the reference count.
 894
 895     Can be \c NULL.
 896     @endparblock
 897
 898 @sa bt_trace_get_ref() &mdash;
 899     Increments the reference count of a trace.
 900 */
 901 extern void bt_trace_put_ref(const bt_trace *trace) __BT_NOEXCEPT;
 902
 903 /*!
 904 @brief
 905     Decrements the reference count of the trace
 906     \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
 907
 908 @param _trace
 909     @parblock
 910     Trace of which to decrement the reference count.
 911
 912     Can contain \c NULL.
 913     @endparblock
 914
 915 @bt_pre_assign_expr{_trace}
 916 */
 917 #define BT_TRACE_PUT_REF_AND_RESET(_trace)              \
 918         do {                                            \
 919                 bt_trace_put_ref(_trace);               \
 920                 (_trace) = NULL;                        \
 921         } while (0)
 922
 923 /*!
 924 @brief
 925     Decrements the reference count of the trace \bt_p{_dst}, sets
 926     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 927
 928 This macro effectively moves a trace reference from the expression
 929 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 930 \bt_p{_dst} reference.
 931
 932 @param _dst
 933     @parblock
 934     Destination expression.
 935
 936     Can contain \c NULL.
 937     @endparblock
 938 @param _src
 939     @parblock
 940     Source expression.
 941
 942     Can contain \c NULL.
 943     @endparblock
 944
 945 @bt_pre_assign_expr{_dst}
 946 @bt_pre_assign_expr{_src}
 947 */
 948 #define BT_TRACE_MOVE_REF(_dst, _src)           \
 949         do {                                    \
 950                 bt_trace_put_ref(_dst);         \
 951                 (_dst) = (_src);                \
 952                 (_src) = NULL;                  \
 953         } while (0)
 954
 955 /*! @} */
 956
 957 /*! @} */
 958
 959 #ifdef __cplusplus
 960 }
 961 #endif
 962
 963 #endif /* BABELTRACE2_TRACE_IR_TRACE_H */