include/babeltrace2/trace-ir/clock-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_CLOCK_CLASS_H
   8 #define BABELTRACE2_TRACE_IR_CLOCK_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-clock-cls Clock class
  26 @ingroup api-tir
  27
  28 @brief
  29     Class of \bt_stream clocks.
  30
  31 A <strong><em>clock class</em></strong> is the class of \bt_stream
  32 clocks.
  33
  34 A clock class is a \ref api-tir "trace IR" metadata object.
  35
  36 <em>Stream clocks</em> only exist conceptually in \bt_name because they
  37 are stateful objects. \bt_cp_msg cannot refer to stateful objects
  38 because they must not change while being transported from one
  39 \bt_comp to the other.
  40
  41 Instead of having a stream clock object, messages have a
  42 default \bt_cs: this is a snapshot of the value of a stream's default
  43 clock (a clock class instance):
  44
  45 @image html clocks.png
  46
  47 In the illustration above, notice that:
  48
  49 - \bt_cp_stream (horizontal blue rectangles) are instances of a
  50   \bt_stream_cls (orange).
  51 - A stream class has a default clock class (orange bell alarm clock).
  52 - Each stream has a default clock (yellow bell alarm clock): this is an
  53   instance of the stream's class's default clock class.
  54 - Each \bt_msg (objects in blue stream rectangles) created for a given
  55   stream has a default \bt_cs (yellow star): this is a snapshot of the
  56   stream's default clock.
  57
  58   In other words, a default clock snapshot contains the value of the
  59   stream's default clock when this message occurred.
  60
  61 The default clock class property of a \bt_stream_cls is optional:
  62 if a stream class has no default clock class, then its instances
  63 (\bt_p_stream) have no default clock, therefore all the \bt_p_msg
  64 created from this stream have no default clock snapshot.
  65
  66 A clock class is a \ref api-fund-shared-object "shared object": get a
  67 new reference with bt_clock_class_get_ref() and put an existing
  68 reference with bt_clock_class_put_ref().
  69
  70 Some library functions \ref api-fund-freezing "freeze" clock classes on
  71 success. The documentation of those functions indicate this
  72 postcondition.
  73
  74 The type of a clock class is #bt_clock_class.
  75
  76 Create a default clock class from a \bt_self_comp with
  77 bt_clock_class_create().
  78
  79 <h1>\anchor api-tir-clock-cls-origin Clock value vs. clock class origin</h1>
  80
  81 The value of a \bt_stream clock (a conceptual instance of a clock class)
  82 is in <em>cycles</em>. This value is always positive and is relative to
  83 the clock's class's offset, which is relative to its origin.
  84
  85 A clock class's origin is one of:
  86
  87 <dl>
  88   <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_TRUE</dt>
  89   <dd>
  90     The
  91     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
  92
  93     The stream clocks of all the clock classes which have a Unix
  94     epoch origin, whatever the clock class
  95     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUIDs</a>,
  96     are correlatable.
  97   </dd>
  98
  99   <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_FALSE</dt>
 100   <dd>
 101     Undefined.
 102
 103     In that case, two clock classes which share the same UUID, as
 104     returned by bt_clock_class_get_uuid(), including having no UUID,
 105     also share the same origin: their instances (stream clocks) are
 106     correlatable.
 107   </dd>
 108 </dl>
 109
 110 To compute an effective stream clock value, in cycles from its class's
 111 origin:
 112
 113 -# Convert the clock class's
 114    \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
 115    property to cycles using its
 116    \ref api-tir-clock-cls-prop-freq "frequency".
 117 -# Add the value of 1., the stream clock's value, and the clock class's
 118    \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
 119    property.
 120
 121 Because typical tracer clocks have a high frequency (often 1&nbsp;GHz
 122 and more), an effective stream clock value (cycles since Unix epoch, for
 123 example) can be larger than \c UINT64_MAX. This is why a clock class has
 124 two offset properties (one in seconds and one in cycles): to make it
 125 possible for a stream clock to have smaller values, relative to this
 126 offset.
 127
 128 The bt_clock_class_cycles_to_ns_from_origin(),
 129 bt_util_clock_cycles_to_ns_from_origin(), and
 130 bt_clock_snapshot_get_ns_from_origin() functions convert a stream clock
 131 value (cycles) to an equivalent <em>nanoseconds from origin</em> value
 132 using the relevant clock class properties (frequency and offset).
 133
 134 Those functions perform this computation:
 135
 136 -# Convert the clock class's "offset in cycles" property to seconds
 137    using its frequency.
 138 -# Convert the stream clock's value to seconds using the clock class's
 139    frequency.
 140 -# Add the values of 1., 2., and the clock class's "offset in seconds"
 141    property.
 142 -# Convert the value of 3. to nanoseconds.
 143
 144 The following illustration shows the possible scenarios:
 145
 146 @image html clock-terminology.png
 147
 148 The clock class's "offset in seconds" property can be negative.
 149 For example, considering:
 150
 151 - Frequency: 1000&nbsp;Hz.
 152 - Offset in seconds: −10&nbsp;seconds.
 153 - Offset in cycles: 500&nbsp;cycles (that is, 0.5&nbsp;seconds).
 154 - Stream clock's value: 2000&nbsp;cycles (that is, 2&nbsp;seconds).
 155
 156 Then the computed value is −7.5&nbsp;seconds from origin, or
 157 −7,500,000,000&nbsp;nanoseconds from origin.
 158
 159 <h1>Properties</h1>
 160
 161 A clock class has the following properties:
 162
 163 <dl>
 164   <dt>\anchor api-tir-clock-cls-prop-freq Frequency</dt>
 165   <dd>
 166     Frequency of the clock class's instances (stream clocks)
 167     (cycles/second).
 168
 169     Use bt_clock_class_set_frequency() and
 170     bt_clock_class_get_frequency().
 171   </dd>
 172
 173   <dt>
 174     \anchor api-tir-clock-cls-prop-offset
 175     Offset (in seconds and in cycles)
 176   </dt>
 177   <dd>
 178     Offset in seconds relative to the clock class's
 179     \ref api-tir-clock-cls-origin "origin", and offset in cycles
 180     relative to the offset in seconds, of the clock class's
 181     instances (stream clocks).
 182
 183     The values of the clock class's instances are relative to the
 184     computed offset.
 185
 186     Use bt_clock_class_set_offset() and bt_clock_class_get_offset().
 187   </dd>
 188
 189   <dt>\anchor api-tir-clock-cls-prop-precision Precision</dt>
 190   <dd>
 191     Precision of the clock class's instance (stream clocks) values
 192     (cycles).
 193
 194     For example, considering a precision of 7&nbsp;cycles and the stream
 195     clock value 42&nbsp;cycles, the real stream clock value can be
 196     anything between 35&nbsp;cycles and 49&nbsp;cycles.
 197
 198     Use bt_clock_class_set_precision() and
 199     bt_clock_class_get_precision().
 200   </dd>
 201
 202   <dt>
 203     \anchor api-tir-clock-cls-prop-origin-unix-epoch
 204     Origin is Unix epoch?
 205   </dt>
 206   <dd>
 207     Whether or not the clock class's
 208     \ref api-tir-clock-cls-origin "origin"
 209     is the
 210     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
 211
 212     Use bt_clock_class_set_origin_is_unix_epoch() and
 213     bt_clock_class_origin_is_unix_epoch().
 214   </dd>
 215
 216   <dt>\anchor api-tir-clock-cls-prop-name \bt_dt_opt Name</dt>
 217   <dd>
 218     Name of the clock class.
 219
 220     Use bt_clock_class_set_name() and bt_clock_class_get_name().
 221   </dd>
 222
 223   <dt>\anchor api-tir-clock-cls-prop-descr \bt_dt_opt Description</dt>
 224   <dd>
 225     Description of the clock class.
 226
 227     Use bt_clock_class_set_description() and
 228     bt_clock_class_get_description().
 229   </dd>
 230
 231   <dt>\anchor api-tir-clock-cls-prop-uuid \bt_dt_opt UUID</dt>
 232   <dd>
 233     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
 234     of the clock class.
 235
 236     The clock class's UUID uniquely identifies the clock class.
 237
 238     When the clock class's origin is \em not the
 239     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>,
 240     then the clock class's UUID determines whether or not two different
 241     clock classes have correlatable instances.
 242
 243     Use bt_clock_class_set_uuid() and bt_clock_class_get_uuid().
 244   </dd>
 245
 246   <dt>
 247     \anchor api-tir-clock-cls-prop-user-attrs
 248     \bt_dt_opt User attributes
 249   </dt>
 250   <dd>
 251     User attributes of the clock class.
 252
 253     User attributes are custom attributes attached to a clock class.
 254
 255     Use bt_clock_class_set_user_attributes(),
 256     bt_clock_class_borrow_user_attributes(), and
 257     bt_clock_class_borrow_user_attributes_const().
 258   </dd>
 259 </dl>
 260 */
 261
 262 /*! @{ */
 263
 264 /*!
 265 @name Type
 266 @{
 267
 268 @typedef struct bt_clock_class bt_clock_class;
 269
 270 @brief
 271     Clock class.
 272
 273 @}
 274 */
 275
 276 /*!
 277 @name Creation
 278 @{
 279 */
 280
 281 /*!
 282 @brief
 283     Creates a default clock class from the \bt_self_comp
 284     \bt_p{self_component}.
 285
 286 On success, the returned clock class has the following property values:
 287
 288 <table>
 289   <tr>
 290     <th>Property
 291     <th>Value
 292   <tr>
 293     <td>\ref api-tir-clock-cls-prop-freq "Frequency"
 294     <td>1&nbsp;GHz
 295   <tr>
 296     <td>\ref api-tir-clock-cls-prop-offset "Offset" in seconds
 297     <td>0&nbsp;seconds
 298   <tr>
 299     <td>\ref api-tir-clock-cls-prop-offset "Offset" in cycles
 300     <td>0&nbsp;cycles
 301   <tr>
 302     <td>\ref api-tir-clock-cls-prop-precision "Precision"
 303     <td>0&nbsp;cycles
 304   <tr>
 305     <td>\ref api-tir-clock-cls-prop-origin-unix-epoch "Origin is Unix epoch?"
 306     <td>Yes
 307   <tr>
 308     <td>\ref api-tir-clock-cls-prop-name "Name"
 309     <td>\em None
 310   <tr>
 311     <td>\ref api-tir-clock-cls-prop-descr "Description"
 312     <td>\em None
 313   <tr>
 314     <td>\ref api-tir-clock-cls-prop-uuid "UUID"
 315     <td>\em None
 316   <tr>
 317     <td>\ref api-tir-clock-cls-prop-user-attrs "User attributes"
 318     <td>Empty \bt_map_val
 319 </table>
 320
 321 @param[in] self_component
 322     Self component from which to create the default clock class.
 323
 324 @returns
 325     New clock class reference, or \c NULL on memory error.
 326
 327 @bt_pre_not_null{self_component}
 328 */
 329 extern bt_clock_class *bt_clock_class_create(bt_self_component *self_component)
 330                 __BT_NOEXCEPT;
 331
 332 /*! @} */
 333
 334 /*!
 335 @name Properties
 336 @{
 337 */
 338
 339 /*!
 340 @brief
 341     Sets the frequency (Hz) of the clock class \bt_p{clock_class} to
 342     \bt_p{frequency}.
 343
 344 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
 345
 346 @param[in] clock_class
 347     Clock class of which to set the frequency to \bt_p{frequency}.
 348 @param[in] frequency
 349     New frequency of \bt_p{clock_class}.
 350
 351 @bt_pre_not_null{clock_class}
 352 @bt_pre_hot{clock_class}
 353 @pre
 354     \bt_p{frequency} is not 0.
 355 @pre
 356     \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
 357 @pre
 358     \bt_p{frequency} is greater than the clock class's offset in cycles
 359     (as returned by bt_clock_class_get_offset()).
 360
 361 @sa bt_clock_class_get_frequency() &mdash;
 362     Returns the frequency of a clock class.
 363 */
 364 extern void bt_clock_class_set_frequency(bt_clock_class *clock_class,
 365                 uint64_t frequency) __BT_NOEXCEPT;
 366
 367 /*!
 368 @brief
 369     Returns the frequency (Hz) of the clock class \bt_p{clock_class}.
 370
 371 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
 372
 373 @param[in] clock_class
 374     Clock class of which to get the frequency.
 375
 376 @returns
 377     Frequency (Hz) of \bt_p{clock_class}.
 378
 379 @bt_pre_not_null{clock_class}
 380
 381 @sa bt_clock_class_set_frequency() &mdash;
 382     Sets the frequency of a clock class.
 383 */
 384 extern uint64_t bt_clock_class_get_frequency(
 385                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 386
 387 /*!
 388 @brief
 389     Sets the offset of the clock class \bt_p{clock_class} to
 390     \bt_p{offset_seconds} plus \bt_p{offset_cycles} from its
 391     \ref api-tir-clock-cls-origin "origin".
 392
 393 See the \ref api-tir-clock-cls-prop-offset "offset" property.
 394
 395 @param[in] clock_class
 396     Clock class of which to set the offset to \bt_p{offset_seconds}
 397     and \bt_p{offset_cycles}.
 398 @param[in] offset_seconds
 399     New offset in seconds of \bt_p{clock_class}.
 400 @param[in] offset_cycles
 401     New offset in cycles of \bt_p{clock_class}.
 402
 403 @bt_pre_not_null{clock_class}
 404 @bt_pre_hot{clock_class}
 405 @pre
 406     \bt_p{offset_cycles} is less than the clock class's frequency
 407     (as returned by bt_clock_class_get_frequency()).
 408
 409 @sa bt_clock_class_get_offset() &mdash;
 410     Returns the offset of a clock class.
 411 */
 412 extern void bt_clock_class_set_offset(bt_clock_class *clock_class,
 413                 int64_t offset_seconds, uint64_t offset_cycles) __BT_NOEXCEPT;
 414
 415 /*!
 416 @brief
 417     Returns the offsets in seconds and cycles of the clock class
 418     \bt_p{clock_class}.
 419
 420 See the \ref api-tir-clock-cls-prop-offset "offset" property.
 421
 422 @param[in] clock_class
 423     Clock class of which to get the offset.
 424 @param[out] offset_seconds
 425     When this function returns, \bt_p{*offset_seconds} is the offset in
 426     seconds of
 427     \bt_p{clock_class}.
 428 @param[out] offset_cycles
 429     When this function returns, \bt_p{*offset_cycles} is the offset in
 430     cycles of \bt_p{clock_class}.
 431
 432 @bt_pre_not_null{clock_class}
 433 @bt_pre_not_null{offset_seconds}
 434 @bt_pre_not_null{offset_cycles}
 435
 436 @sa bt_clock_class_set_offset() &mdash;
 437     Sets the offset of a clock class.
 438 */
 439 extern void bt_clock_class_get_offset(const bt_clock_class *clock_class,
 440                 int64_t *offset_seconds, uint64_t *offset_cycles) __BT_NOEXCEPT;
 441
 442 /*!
 443 @brief
 444     Sets the precision (cycles) of the clock class \bt_p{clock_class} to
 445     \bt_p{precision}.
 446
 447 See the \ref api-tir-clock-cls-prop-precision "precision" property.
 448
 449 @param[in] clock_class
 450     Clock class of which to set the precision to \bt_p{precision}.
 451 @param[in] precision
 452     New precision of \bt_p{clock_class}.
 453
 454 @bt_pre_not_null{clock_class}
 455 @bt_pre_hot{clock_class}
 456
 457 @sa bt_clock_class_get_precision() &mdash;
 458     Returns the precision of a clock class.
 459 */
 460 extern void bt_clock_class_set_precision(bt_clock_class *clock_class,
 461                 uint64_t precision) __BT_NOEXCEPT;
 462
 463 /*!
 464 @brief
 465     Returns the precision (cycles) of the clock class
 466     \bt_p{clock_class}.
 467
 468 See the \ref api-tir-clock-cls-prop-precision "precision" property.
 469
 470 @param[in] clock_class
 471     Clock class of which to get the precision.
 472
 473 @returns
 474     Precision (cycles) of \bt_p{clock_class}.
 475
 476 @bt_pre_not_null{clock_class}
 477
 478 @sa bt_clock_class_set_precision() &mdash;
 479     Sets the precision of a clock class.
 480 */
 481 extern uint64_t bt_clock_class_get_precision(
 482                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 483
 484 /*!
 485 @brief
 486     Sets whether or not the \ref api-tir-clock-cls-origin "origin"
 487     of the clock class \bt_p{clock_class} is the
 488     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
 489
 490 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
 491 property.
 492
 493 @param[in] clock_class
 494     Clock class of which to set whether or not its origin is the
 495     Unix epoch.
 496 @param[in] origin_is_unix_epoch
 497     #BT_TRUE to make \bt_p{clock_class} have a Unix epoch origin.
 498
 499 @bt_pre_not_null{clock_class}
 500 @bt_pre_hot{clock_class}
 501
 502 @sa bt_clock_class_origin_is_unix_epoch() &mdash;
 503     Returns whether or not the origin of a clock class is the
 504     Unix epoch.
 505 */
 506 extern void bt_clock_class_set_origin_is_unix_epoch(bt_clock_class *clock_class,
 507                 bt_bool origin_is_unix_epoch) __BT_NOEXCEPT;
 508
 509 /*!
 510 @brief
 511     Returns whether or not the \ref api-tir-clock-cls-origin "origin"
 512     of the clock class \bt_p{clock_class} is the
 513     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
 514
 515 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
 516 property.
 517
 518 @param[in] clock_class
 519     Clock class of which to get whether or not its origin is the
 520     Unix epoch.
 521
 522 @returns
 523     #BT_TRUE if the origin of \bt_p{clock_class} is the Unix epoch.
 524
 525 @bt_pre_not_null{clock_class}
 526
 527 @sa bt_clock_class_set_origin_is_unix_epoch() &mdash;
 528     Sets whether or not the origin of a clock class is the Unix epoch.
 529 */
 530 extern bt_bool bt_clock_class_origin_is_unix_epoch(
 531                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 532
 533 /*!
 534 @brief
 535     Status codes for bt_clock_class_set_name().
 536 */
 537 typedef enum bt_clock_class_set_name_status {
 538         /*!
 539         @brief
 540             Success.
 541         */
 542         BT_CLOCK_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
 543
 544         /*!
 545         @brief
 546             Out of memory.
 547         */
 548         BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 549 } bt_clock_class_set_name_status;
 550
 551 /*!
 552 @brief
 553     Sets the name of the clock class \bt_p{clock_class} to
 554     a copy of \bt_p{name}.
 555
 556 See the \ref api-tir-clock-cls-prop-name "name" property.
 557
 558 @param[in] clock_class
 559     Clock class of which to set the name to \bt_p{name}.
 560 @param[in] name
 561     New name of \bt_p{clock_class} (copied).
 562
 563 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_OK
 564     Success.
 565 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 566     Out of memory.
 567
 568 @bt_pre_not_null{clock_class}
 569 @bt_pre_hot{clock_class}
 570 @bt_pre_not_null{name}
 571
 572 @sa bt_clock_class_get_name() &mdash;
 573     Returns the name of a clock class.
 574 */
 575 extern bt_clock_class_set_name_status bt_clock_class_set_name(
 576                 bt_clock_class *clock_class, const char *name) __BT_NOEXCEPT;
 577
 578 /*!
 579 @brief
 580     Returns the name of the clock class \bt_p{clock_class}.
 581
 582 See the \ref api-tir-clock-cls-prop-name "name" property.
 583
 584 If \bt_p{clock_class} has no name, this function returns \c NULL.
 585
 586 @param[in] clock_class
 587     Clock class of which to get the name.
 588
 589 @returns
 590     @parblock
 591     Name of \bt_p{clock_class}, or \c NULL if none.
 592
 593     The returned pointer remains valid as long as \bt_p{clock_class}
 594     is not modified.
 595     @endparblock
 596
 597 @bt_pre_not_null{clock_class}
 598
 599 @sa bt_clock_class_set_name() &mdash;
 600     Sets the name of a clock class.
 601 */
 602 extern const char *bt_clock_class_get_name(
 603                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 604
 605 /*!
 606 @brief
 607     Status codes for bt_clock_class_set_description().
 608 */
 609 typedef enum bt_clock_class_set_description_status {
 610         /*!
 611         @brief
 612             Success.
 613         */
 614         BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK                = __BT_FUNC_STATUS_OK,
 615
 616         /*!
 617         @brief
 618             Out of memory.
 619         */
 620         BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 621 } bt_clock_class_set_description_status;
 622
 623 /*!
 624 @brief
 625     Sets the description of the clock class \bt_p{clock_class} to a copy
 626     of \bt_p{description}.
 627
 628 See the \ref api-tir-clock-cls-prop-descr "description" property.
 629
 630 @param[in] clock_class
 631     Clock class of which to set the description to \bt_p{description}.
 632 @param[in] description
 633     New description of \bt_p{clock_class} (copied).
 634
 635 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK
 636     Success.
 637 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
 638     Out of memory.
 639
 640 @bt_pre_not_null{clock_class}
 641 @bt_pre_hot{clock_class}
 642 @bt_pre_not_null{description}
 643
 644 @sa bt_clock_class_get_description() &mdash;
 645     Returns the description of a clock class.
 646 */
 647 extern bt_clock_class_set_description_status bt_clock_class_set_description(
 648                 bt_clock_class *clock_class, const char *description)
 649                 __BT_NOEXCEPT;
 650
 651 /*!
 652 @brief
 653     Returns the description of the clock class \bt_p{clock_class}.
 654
 655 See the \ref api-tir-clock-cls-prop-descr "description" property.
 656
 657 If \bt_p{clock_class} has no description, this function returns \c NULL.
 658
 659 @param[in] clock_class
 660     Clock class of which to get the description.
 661
 662 @returns
 663     @parblock
 664     Description of \bt_p{clock_class}, or \c NULL if none.
 665
 666     The returned pointer remains valid as long as \bt_p{clock_class}
 667     is not modified.
 668     @endparblock
 669
 670 @bt_pre_not_null{clock_class}
 671
 672 @sa bt_clock_class_set_description() &mdash;
 673     Sets the description of a clock class.
 674 */
 675 extern const char *bt_clock_class_get_description(
 676                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 677
 678 /*!
 679 @brief
 680     Sets the
 681     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
 682     of the clock class \bt_p{clock_class} to a copy of \bt_p{uuid}.
 683
 684 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
 685
 686 @param[in] clock_class
 687     Clock class of which to set the UUID to \bt_p{uuid}.
 688 @param[in] uuid
 689     New UUID of \bt_p{clock_class} (copied).
 690
 691 @bt_pre_not_null{clock_class}
 692 @bt_pre_hot{clock_class}
 693 @bt_pre_not_null{uuid}
 694
 695 @sa bt_clock_class_get_uuid() &mdash;
 696     Returns the UUID of a clock class.
 697 */
 698 extern void bt_clock_class_set_uuid(bt_clock_class *clock_class,
 699                 bt_uuid uuid) __BT_NOEXCEPT;
 700
 701 /*!
 702 @brief
 703     Returns the UUID of the clock class \bt_p{clock_class}.
 704
 705 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
 706
 707 If \bt_p{clock_class} has no UUID, this function returns \c NULL.
 708
 709 @param[in] clock_class
 710     Clock class of which to get the UUID.
 711
 712 @returns
 713     @parblock
 714     UUID of \bt_p{clock_class}, or \c NULL if none.
 715
 716     The returned pointer remains valid as long as \bt_p{clock_class}
 717     is not modified.
 718     @endparblock
 719
 720 @bt_pre_not_null{clock_class}
 721
 722 @sa bt_clock_class_set_uuid() &mdash;
 723     Sets the UUID of a clock class.
 724 */
 725 extern bt_uuid bt_clock_class_get_uuid(
 726                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 727
 728 /*!
 729 @brief
 730     Sets the user attributes of the clock class \bt_p{clock_class} to
 731     \bt_p{user_attributes}.
 732
 733 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
 734 property.
 735
 736 @note
 737     When you create a default clock class with bt_clock_class_create(),
 738     the clock class's initial user attributes is an empty \bt_map_val.
 739     Therefore you can borrow it with
 740     bt_clock_class_borrow_user_attributes() and fill it directly instead
 741     of setting a new one with this function.
 742
 743 @param[in] clock_class
 744     Clock class of which to set the user attributes to
 745     \bt_p{user_attributes}.
 746 @param[in] user_attributes
 747     New user attributes of \bt_p{clock_class}.
 748
 749 @bt_pre_not_null{clock_class}
 750 @bt_pre_hot{clock_class}
 751 @bt_pre_not_null{user_attributes}
 752 @bt_pre_is_map_val{user_attributes}
 753
 754 @sa bt_clock_class_borrow_user_attributes() &mdash;
 755     Borrows the user attributes of a clock class.
 756 */
 757 extern void bt_clock_class_set_user_attributes(
 758                 bt_clock_class *clock_class, const bt_value *user_attributes)
 759                 __BT_NOEXCEPT;
 760
 761 /*!
 762 @brief
 763     Borrows the user attributes of the clock class \bt_p{clock_class}.
 764
 765 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
 766 property.
 767
 768 @note
 769     When you create a default clock class with bt_clock_class_create(),
 770     the clock class's initial user attributes is an empty \bt_map_val.
 771
 772 @param[in] clock_class
 773     Clock class from which to borrow the user attributes.
 774
 775 @returns
 776     User attributes of \bt_p{clock_class} (a \bt_map_val).
 777
 778 @bt_pre_not_null{clock_class}
 779
 780 @sa bt_clock_class_set_user_attributes() &mdash;
 781     Sets the user attributes of a clock class.
 782 @sa bt_clock_class_borrow_user_attributes_const() &mdash;
 783     \c const version of this function.
 784 */
 785 extern bt_value *bt_clock_class_borrow_user_attributes(
 786                 bt_clock_class *clock_class) __BT_NOEXCEPT;
 787
 788 /*!
 789 @brief
 790     Borrows the user attributes of the clock class \bt_p{clock_class}
 791     (\c const version).
 792
 793 See bt_clock_class_borrow_user_attributes().
 794 */
 795 extern const bt_value *bt_clock_class_borrow_user_attributes_const(
 796                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 797
 798 /*! @} */
 799
 800 /*!
 801 @name Utilities
 802 @{
 803 */
 804
 805 /*!
 806 @brief
 807     Status codes for bt_clock_class_cycles_to_ns_from_origin().
 808 */
 809 typedef enum bt_clock_class_cycles_to_ns_from_origin_status {
 810         /*!
 811         @brief
 812             Success.
 813         */
 814         BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
 815
 816         /*!
 817         @brief
 818             Integer overflow while computing the result.
 819         */
 820         BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR   = __BT_FUNC_STATUS_OVERFLOW_ERROR,
 821 } bt_clock_class_cycles_to_ns_from_origin_status;
 822
 823 /*!
 824 @brief
 825     Converts the stream clock value \bt_p{value} from cycles to
 826     nanoseconds from the \ref api-tir-clock-cls-origin "origin" of the
 827     clock class \bt_p{clock_class} and sets \bt_p{*ns_from_origin}
 828     to the result.
 829
 830 This function:
 831
 832 -# Converts the
 833    \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
 834    property of \bt_p{clock_class} to seconds using its
 835    \ref api-tir-clock-cls-prop-freq "frequency".
 836 -# Converts the \bt_p{value} value to seconds using the frequency of
 837    \bt_p{clock_class}.
 838 -# Adds the values of 1., 2., and the
 839    \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
 840    property of \bt_p{clock_class}.
 841 -# Converts the value of 3. to nanoseconds and sets
 842    \bt_p{*ns_from_origin} to this result.
 843
 844 The following illustration shows the possible scenarios:
 845
 846 @image html clock-terminology.png
 847
 848 This function can fail and return the
 849 #BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
 850 code if any step of the computation process causes an integer overflow.
 851
 852 @param[in] clock_class
 853     Stream clock's class.
 854 @param[in] value
 855     Stream clock's value (cycles) to convert to nanoseconds from
 856     the origin of \bt_p{clock_class}.
 857 @param[out] ns_from_origin
 858     <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{value}
 859     converted to nanoseconds from the origin of \bt_p{clock_class}.
 860
 861 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
 862     Success.
 863 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
 864     Integer overflow while computing the result.
 865
 866 @bt_pre_not_null{clock_class}
 867 @bt_pre_not_null{ns_from_origin}
 868
 869 @sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
 870     Converts a clock value from cycles to nanoseconds from the clock's
 871     origin.
 872 */
 873 extern bt_clock_class_cycles_to_ns_from_origin_status
 874 bt_clock_class_cycles_to_ns_from_origin(
 875                 const bt_clock_class *clock_class,
 876                 uint64_t value, int64_t *ns_from_origin) __BT_NOEXCEPT;
 877
 878 /*! @} */
 879
 880 /*!
 881 @name Reference count
 882 @{
 883 */
 884
 885 /*!
 886 @brief
 887     Increments the \ref api-fund-shared-object "reference count" of
 888     the clock class \bt_p{clock_class}.
 889
 890 @param[in] clock_class
 891     @parblock
 892     Clock class of which to increment the reference count.
 893
 894     Can be \c NULL.
 895     @endparblock
 896
 897 @sa bt_clock_class_put_ref() &mdash;
 898     Decrements the reference count of a clock class.
 899 */
 900 extern void bt_clock_class_get_ref(
 901                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 902
 903 /*!
 904 @brief
 905     Decrements the \ref api-fund-shared-object "reference count" of
 906     the clock class \bt_p{clock_class}.
 907
 908 @param[in] clock_class
 909     @parblock
 910     Clock class of which to decrement the reference count.
 911
 912     Can be \c NULL.
 913     @endparblock
 914
 915 @sa bt_clock_class_get_ref() &mdash;
 916     Increments the reference count of a clock class.
 917 */
 918 extern void bt_clock_class_put_ref(
 919                 const bt_clock_class *clock_class) __BT_NOEXCEPT;
 920
 921 /*!
 922 @brief
 923     Decrements the reference count of the clock class
 924     \bt_p{_clock_class}, and then sets \bt_p{_clock_class} to \c NULL.
 925
 926 @param _clock_class
 927     @parblock
 928     Clock class of which to decrement the reference count.
 929
 930     Can contain \c NULL.
 931     @endparblock
 932
 933 @bt_pre_assign_expr{_clock_class}
 934 */
 935 #define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_clock_class)  \
 936         do {                                            \
 937                 bt_clock_class_put_ref(_clock_class);   \
 938                 (_clock_class) = NULL;                  \
 939         } while (0)
 940
 941 /*!
 942 @brief
 943     Decrements the reference count of the clock class \bt_p{_dst}, sets
 944     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 945
 946 This macro effectively moves a clock class reference from the expression
 947 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 948 \bt_p{_dst} reference.
 949
 950 @param _dst
 951     @parblock
 952     Destination expression.
 953
 954     Can contain \c NULL.
 955     @endparblock
 956 @param _src
 957     @parblock
 958     Source expression.
 959
 960     Can contain \c NULL.
 961     @endparblock
 962
 963 @bt_pre_assign_expr{_dst}
 964 @bt_pre_assign_expr{_src}
 965 */
 966 #define BT_CLOCK_CLASS_MOVE_REF(_dst, _src)     \
 967         do {                                    \
 968                 bt_clock_class_put_ref(_dst);   \
 969                 (_dst) = (_src);                \
 970                 (_src) = NULL;                  \
 971         } while (0)
 972
 973 /*! @} */
 974
 975 /*! @} */
 976
 977 #ifdef __cplusplus
 978 }
 979 #endif
 980
 981 #endif /* BABELTRACE2_TRACE_IR_CLOCK_CLASS_H */