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