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