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
 331 /*! @} */
 332
 333 /*!
 334 @name Properties
 335 @{
 336 */
 337
 338 /*!
 339 @brief
 340     Sets the frequency (Hz) of the clock class \bt_p{clock_class} to
 341     \bt_p{frequency}.
 342
 343 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
 344
 345 @param[in] clock_class
 346     Clock class of which to set the frequency to \bt_p{frequency}.
 347 @param[in] frequency
 348     New frequency of \bt_p{clock_class}.
 349
 350 @bt_pre_not_null{clock_class}
 351 @bt_pre_hot{clock_class}
 352 @pre
 353     \bt_p{frequency} is not 0.
 354 @pre
 355     \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
 356 @pre
 357     \bt_p{frequency} is greater than the clock class's offset in cycles
 358     (as returned by bt_clock_class_get_offset()).
 359
 360 @sa bt_clock_class_get_frequency() &mdash;
 361     Returns the frequency of a clock class.
 362 */
 363 extern void bt_clock_class_set_frequency(bt_clock_class *clock_class,
 364                 uint64_t frequency);
 365
 366 /*!
 367 @brief
 368     Returns the frequency (Hz) of the clock class \bt_p{clock_class}.
 369
 370 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
 371
 372 @param[in] clock_class
 373     Clock class of which to get the frequency.
 374
 375 @returns
 376     Frequency (Hz) of \bt_p{clock_class}.
 377
 378 @bt_pre_not_null{clock_class}
 379
 380 @sa bt_clock_class_set_frequency() &mdash;
 381     Sets the frequency of a clock class.
 382 */
 383 extern uint64_t bt_clock_class_get_frequency(
 384                 const bt_clock_class *clock_class);
 385
 386 /*!
 387 @brief
 388     Sets the offset of the clock class \bt_p{clock_class} to
 389     \bt_p{offset_seconds} plus \bt_p{offset_cycles} from its
 390     \ref api-tir-clock-cls-origin "origin".
 391
 392 See the \ref api-tir-clock-cls-prop-offset "offset" property.
 393
 394 @param[in] clock_class
 395     Clock class of which to set the offset to \bt_p{offset_seconds}
 396     and \bt_p{offset_cycles}.
 397 @param[in] offset_seconds
 398     New offset in seconds of \bt_p{clock_class}.
 399 @param[in] offset_cycles
 400     New offset in cycles of \bt_p{clock_class}.
 401
 402 @bt_pre_not_null{clock_class}
 403 @bt_pre_hot{clock_class}
 404 @pre
 405     \bt_p{offset_cycles} is less than the clock class's frequency
 406     (as returned by bt_clock_class_get_frequency()).
 407
 408 @sa bt_clock_class_get_offset() &mdash;
 409     Returns the offset of a clock class.
 410 */
 411 extern void bt_clock_class_set_offset(bt_clock_class *clock_class,
 412                 int64_t offset_seconds, uint64_t offset_cycles);
 413
 414 /*!
 415 @brief
 416     Returns the offsets in seconds and cycles of the clock class
 417     \bt_p{clock_class}.
 418
 419 See the \ref api-tir-clock-cls-prop-offset "offset" property.
 420
 421 @param[in] clock_class
 422     Clock class of which to get the offset.
 423 @param[out] offset_seconds
 424     When this function returns, \bt_p{*offset_seconds} is the offset in
 425     seconds of
 426     \bt_p{clock_class}.
 427 @param[out] offset_cycles
 428     When this function returns, \bt_p{*offset_cycles} is the offset in
 429     cycles of \bt_p{clock_class}.
 430
 431 @bt_pre_not_null{clock_class}
 432 @bt_pre_not_null{offset_seconds}
 433 @bt_pre_not_null{offset_cycles}
 434
 435 @sa bt_clock_class_set_offset() &mdash;
 436     Sets the offset of a clock class.
 437 */
 438 extern void bt_clock_class_get_offset(const bt_clock_class *clock_class,
 439                 int64_t *offset_seconds, uint64_t *offset_cycles);
 440
 441 /*!
 442 @brief
 443     Sets the precision (cycles) of the clock class \bt_p{clock_class} to
 444     \bt_p{precision}.
 445
 446 See the \ref api-tir-clock-cls-prop-precision "precision" property.
 447
 448 @param[in] clock_class
 449     Clock class of which to set the precision to \bt_p{precision}.
 450 @param[in] precision
 451     New precision of \bt_p{clock_class}.
 452
 453 @bt_pre_not_null{clock_class}
 454 @bt_pre_hot{clock_class}
 455
 456 @sa bt_clock_class_get_precision() &mdash;
 457     Returns the precision of a clock class.
 458 */
 459 extern void bt_clock_class_set_precision(bt_clock_class *clock_class,
 460                 uint64_t precision);
 461
 462 /*!
 463 @brief
 464     Returns the precision (cycles) of the clock class
 465     \bt_p{clock_class}.
 466
 467 See the \ref api-tir-clock-cls-prop-precision "precision" property.
 468
 469 @param[in] clock_class
 470     Clock class of which to get the precision.
 471
 472 @returns
 473     Precision (cycles) of \bt_p{clock_class}.
 474
 475 @bt_pre_not_null{clock_class}
 476
 477 @sa bt_clock_class_set_precision() &mdash;
 478     Sets the precision of a clock class.
 479 */
 480 extern uint64_t bt_clock_class_get_precision(
 481                 const bt_clock_class *clock_class);
 482
 483 /*!
 484 @brief
 485     Sets whether or not the \ref api-tir-clock-cls-origin "origin"
 486     of the clock class \bt_p{clock_class} is the
 487     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
 488
 489 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
 490 property.
 491
 492 @param[in] clock_class
 493     Clock class of which to set whether or not its origin is the
 494     Unix epoch.
 495 @param[in] origin_is_unix_epoch
 496     #BT_TRUE to make \bt_p{clock_class} have a Unix epoch origin.
 497
 498 @bt_pre_not_null{clock_class}
 499 @bt_pre_hot{clock_class}
 500
 501 @sa bt_clock_class_origin_is_unix_epoch() &mdash;
 502     Returns whether or not the origin of a clock class is the
 503     Unix epoch.
 504 */
 505 extern void bt_clock_class_set_origin_is_unix_epoch(bt_clock_class *clock_class,
 506                 bt_bool origin_is_unix_epoch);
 507
 508 /*!
 509 @brief
 510     Returns whether or not the \ref api-tir-clock-cls-origin "origin"
 511     of the clock class \bt_p{clock_class} is the
 512     <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
 513
 514 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
 515 property.
 516
 517 @param[in] clock_class
 518     Clock class of which to get whether or not its origin is the
 519     Unix epoch.
 520
 521 @returns
 522     #BT_TRUE if the origin of \bt_p{clock_class} is the Unix epoch.
 523
 524 @bt_pre_not_null{clock_class}
 525
 526 @sa bt_clock_class_set_origin_is_unix_epoch() &mdash;
 527     Sets whether or not the origin of a clock class is the Unix epoch.
 528 */
 529 extern bt_bool bt_clock_class_origin_is_unix_epoch(
 530                 const bt_clock_class *clock_class);
 531
 532 /*!
 533 @brief
 534     Status codes for bt_clock_class_set_name().
 535 */
 536 typedef enum bt_clock_class_set_name_status {
 537         /*!
 538         @brief
 539             Success.
 540         */
 541         BT_CLOCK_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
 542
 543         /*!
 544         @brief
 545             Out of memory.
 546         */
 547         BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 548 } bt_clock_class_set_name_status;
 549
 550 /*!
 551 @brief
 552     Sets the name of the clock class \bt_p{clock_class} to
 553     a copy of \bt_p{name}.
 554
 555 See the \ref api-tir-clock-cls-prop-name "name" property.
 556
 557 @param[in] clock_class
 558     Clock class of which to set the name to \bt_p{name}.
 559 @param[in] name
 560     New name of \bt_p{clock_class} (copied).
 561
 562 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_OK
 563     Success.
 564 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
 565     Out of memory.
 566
 567 @bt_pre_not_null{clock_class}
 568 @bt_pre_hot{clock_class}
 569 @bt_pre_not_null{name}
 570
 571 @sa bt_clock_class_get_name() &mdash;
 572     Returns the name of a clock class.
 573 */
 574 extern bt_clock_class_set_name_status bt_clock_class_set_name(
 575                 bt_clock_class *clock_class, const char *name);
 576
 577 /*!
 578 @brief
 579     Returns the name of the clock class \bt_p{clock_class}.
 580
 581 See the \ref api-tir-clock-cls-prop-name "name" property.
 582
 583 If \bt_p{clock_class} has no name, this function returns \c NULL.
 584
 585 @param[in] clock_class
 586     Clock class of which to get the name.
 587
 588 @returns
 589     @parblock
 590     Name of \bt_p{clock_class}, or \c NULL if none.
 591
 592     The returned pointer remains valid as long as \bt_p{clock_class}
 593     is not modified.
 594     @endparblock
 595
 596 @bt_pre_not_null{clock_class}
 597
 598 @sa bt_clock_class_set_name() &mdash;
 599     Sets the name of a clock class.
 600 */
 601 extern const char *bt_clock_class_get_name(
 602                 const bt_clock_class *clock_class);
 603
 604 /*!
 605 @brief
 606     Status codes for bt_clock_class_set_description().
 607 */
 608 typedef enum bt_clock_class_set_description_status {
 609         /*!
 610         @brief
 611             Success.
 612         */
 613         BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK                = __BT_FUNC_STATUS_OK,
 614
 615         /*!
 616         @brief
 617             Out of memory.
 618         */
 619         BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 620 } bt_clock_class_set_description_status;
 621
 622 /*!
 623 @brief
 624     Sets the description of the clock class \bt_p{clock_class} to a copy
 625     of \bt_p{description}.
 626
 627 See the \ref api-tir-clock-cls-prop-descr "description" property.
 628
 629 @param[in] clock_class
 630     Clock class of which to set the description to \bt_p{description}.
 631 @param[in] description
 632     New description of \bt_p{clock_class} (copied).
 633
 634 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK
 635     Success.
 636 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
 637     Out of memory.
 638
 639 @bt_pre_not_null{clock_class}
 640 @bt_pre_hot{clock_class}
 641 @bt_pre_not_null{description}
 642
 643 @sa bt_clock_class_get_description() &mdash;
 644     Returns the description of a clock class.
 645 */
 646 extern bt_clock_class_set_description_status bt_clock_class_set_description(
 647                 bt_clock_class *clock_class, const char *description);
 648
 649 /*!
 650 @brief
 651     Returns the description of the clock class \bt_p{clock_class}.
 652
 653 See the \ref api-tir-clock-cls-prop-descr "description" property.
 654
 655 If \bt_p{clock_class} has no description, this function returns \c NULL.
 656
 657 @param[in] clock_class
 658     Clock class of which to get the description.
 659
 660 @returns
 661     @parblock
 662     Description of \bt_p{clock_class}, or \c NULL if none.
 663
 664     The returned pointer remains valid as long as \bt_p{clock_class}
 665     is not modified.
 666     @endparblock
 667
 668 @bt_pre_not_null{clock_class}
 669
 670 @sa bt_clock_class_set_description() &mdash;
 671     Sets the description of a clock class.
 672 */
 673 extern const char *bt_clock_class_get_description(
 674                 const bt_clock_class *clock_class);
 675
 676 /*!
 677 @brief
 678     Sets the
 679     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
 680     of the clock class \bt_p{clock_class} to a copy of \bt_p{uuid}.
 681
 682 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
 683
 684 @param[in] clock_class
 685     Clock class of which to set the UUID to \bt_p{uuid}.
 686 @param[in] uuid
 687     New UUID of \bt_p{clock_class} (copied).
 688
 689 @bt_pre_not_null{clock_class}
 690 @bt_pre_hot{clock_class}
 691 @bt_pre_not_null{uuid}
 692
 693 @sa bt_clock_class_get_uuid() &mdash;
 694     Returns the UUID of a clock class.
 695 */
 696 extern void bt_clock_class_set_uuid(bt_clock_class *clock_class,
 697                 bt_uuid uuid);
 698
 699 /*!
 700 @brief
 701     Returns the UUID of the clock class \bt_p{clock_class}.
 702
 703 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
 704
 705 If \bt_p{clock_class} has no UUID, this function returns \c NULL.
 706
 707 @param[in] clock_class
 708     Clock class of which to get the UUID.
 709
 710 @returns
 711     @parblock
 712     UUID of \bt_p{clock_class}, or \c NULL if none.
 713
 714     The returned pointer remains valid as long as \bt_p{clock_class}
 715     is not modified.
 716     @endparblock
 717
 718 @bt_pre_not_null{clock_class}
 719
 720 @sa bt_clock_class_set_uuid() &mdash;
 721     Sets the UUID of a clock class.
 722 */
 723 extern bt_uuid bt_clock_class_get_uuid(
 724                 const bt_clock_class *clock_class);
 725
 726 /*!
 727 @brief
 728     Sets the user attributes of the clock class \bt_p{clock_class} to
 729     \bt_p{user_attributes}.
 730
 731 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
 732 property.
 733
 734 @note
 735     When you create a default clock class with bt_clock_class_create(),
 736     the clock class's initial user attributes is an empty \bt_map_val.
 737     Therefore you can borrow it with
 738     bt_clock_class_borrow_user_attributes() and fill it directly instead
 739     of setting a new one with this function.
 740
 741 @param[in] clock_class
 742     Clock class of which to set the user attributes to
 743     \bt_p{user_attributes}.
 744 @param[in] user_attributes
 745     New user attributes of \bt_p{clock_class}.
 746
 747 @bt_pre_not_null{clock_class}
 748 @bt_pre_hot{clock_class}
 749 @bt_pre_not_null{user_attributes}
 750 @bt_pre_is_map_val{user_attributes}
 751
 752 @sa bt_clock_class_borrow_user_attributes() &mdash;
 753     Borrows the user attributes of a clock class.
 754 */
 755 extern void bt_clock_class_set_user_attributes(
 756                 bt_clock_class *clock_class, const bt_value *user_attributes);
 757
 758 /*!
 759 @brief
 760     Borrows the user attributes of the clock class \bt_p{clock_class}.
 761
 762 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
 763 property.
 764
 765 @note
 766     When you create a default clock class with bt_clock_class_create(),
 767     the clock class's initial user attributes is an empty \bt_map_val.
 768
 769 @param[in] clock_class
 770     Clock class from which to borrow the user attributes.
 771
 772 @returns
 773     User attributes of \bt_p{clock_class} (a \bt_map_val).
 774
 775 @bt_pre_not_null{clock_class}
 776
 777 @sa bt_clock_class_set_user_attributes() &mdash;
 778     Sets the user attributes of a clock class.
 779 @sa bt_clock_class_borrow_user_attributes_const() &mdash;
 780     \c const version of this function.
 781 */
 782 extern bt_value *bt_clock_class_borrow_user_attributes(
 783                 bt_clock_class *clock_class);
 784
 785 /*!
 786 @brief
 787     Borrows the user attributes of the clock class \bt_p{clock_class}
 788     (\c const version).
 789
 790 See bt_clock_class_borrow_user_attributes().
 791 */
 792 extern const bt_value *bt_clock_class_borrow_user_attributes_const(
 793                 const bt_clock_class *clock_class);
 794
 795 /*! @} */
 796
 797 /*!
 798 @name Utilities
 799 @{
 800 */
 801
 802 /*!
 803 @brief
 804     Status codes for bt_clock_class_cycles_to_ns_from_origin().
 805 */
 806 typedef enum bt_clock_class_cycles_to_ns_from_origin_status {
 807         /*!
 808         @brief
 809             Success.
 810         */
 811         BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
 812
 813         /*!
 814         @brief
 815             Integer overflow while computing the result.
 816         */
 817         BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR   = __BT_FUNC_STATUS_OVERFLOW_ERROR,
 818 } bt_clock_class_cycles_to_ns_from_origin_status;
 819
 820 /*!
 821 @brief
 822     Converts the stream clock value \bt_p{value} from cycles to
 823     nanoseconds from the \ref api-tir-clock-cls-origin "origin" of the
 824     clock class \bt_p{clock_class} and sets \bt_p{*ns_from_origin}
 825     to the result.
 826
 827 This function:
 828
 829 -# Converts the
 830    \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
 831    property of \bt_p{clock_class} to seconds using its
 832    \ref api-tir-clock-cls-prop-freq "frequency".
 833 -# Converts the \bt_p{value} value to seconds using the frequency of
 834    \bt_p{clock_class}.
 835 -# Adds the values of 1., 2., and the
 836    \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
 837    property of \bt_p{clock_class}.
 838 -# Converts the value of 3. to nanoseconds and sets
 839    \bt_p{*ns_from_origin} to this result.
 840
 841 The following illustration shows the possible scenarios:
 842
 843 @image html clock-terminology.png
 844
 845 This function can fail and return the
 846 #BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
 847 code if any step of the computation process causes an integer overflow.
 848
 849 @param[in] clock_class
 850     Stream clock's class.
 851 @param[in] value
 852     Stream clock's value (cycles) to convert to nanoseconds from
 853     the origin of \bt_p{clock_class}.
 854 @param[out] ns_from_origin
 855     <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{value}
 856     converted to nanoseconds from the origin of \bt_p{clock_class}.
 857
 858 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
 859     Success.
 860 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
 861     Integer overflow while computing the result.
 862
 863 @bt_pre_not_null{clock_class}
 864 @bt_pre_not_null{ns_from_origin}
 865
 866 @sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
 867     Converts a clock value from cycles to nanoseconds from the clock's
 868     origin.
 869 */
 870 extern bt_clock_class_cycles_to_ns_from_origin_status
 871 bt_clock_class_cycles_to_ns_from_origin(
 872                 const bt_clock_class *clock_class,
 873                 uint64_t value, int64_t *ns_from_origin);
 874
 875 /*! @} */
 876
 877 /*!
 878 @name Reference count
 879 @{
 880 */
 881
 882 /*!
 883 @brief
 884     Increments the \ref api-fund-shared-object "reference count" of
 885     the clock class \bt_p{clock_class}.
 886
 887 @param[in] clock_class
 888     @parblock
 889     Clock class of which to increment the reference count.
 890
 891     Can be \c NULL.
 892     @endparblock
 893
 894 @sa bt_clock_class_put_ref() &mdash;
 895     Decrements the reference count of a clock class.
 896 */
 897 extern void bt_clock_class_get_ref(const bt_clock_class *clock_class);
 898
 899 /*!
 900 @brief
 901     Decrements the \ref api-fund-shared-object "reference count" of
 902     the clock class \bt_p{clock_class}.
 903
 904 @param[in] clock_class
 905     @parblock
 906     Clock class of which to decrement the reference count.
 907
 908     Can be \c NULL.
 909     @endparblock
 910
 911 @sa bt_clock_class_get_ref() &mdash;
 912     Increments the reference count of a clock class.
 913 */
 914 extern void bt_clock_class_put_ref(const bt_clock_class *clock_class);
 915
 916 /*!
 917 @brief
 918     Decrements the reference count of the clock class
 919     \bt_p{_clock_class}, and then sets \bt_p{_clock_class} to \c NULL.
 920
 921 @param _clock_class
 922     @parblock
 923     Clock class of which to decrement the reference count.
 924
 925     Can contain \c NULL.
 926     @endparblock
 927
 928 @bt_pre_assign_expr{_clock_class}
 929 */
 930 #define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_clock_class)  \
 931         do {                                            \
 932                 bt_clock_class_put_ref(_clock_class);   \
 933                 (_clock_class) = NULL;                  \
 934         } while (0)
 935
 936 /*!
 937 @brief
 938     Decrements the reference count of the clock class \bt_p{_dst}, sets
 939     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 940
 941 This macro effectively moves a clock class reference from the expression
 942 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 943 \bt_p{_dst} reference.
 944
 945 @param _dst
 946     @parblock
 947     Destination expression.
 948
 949     Can contain \c NULL.
 950     @endparblock
 951 @param _src
 952     @parblock
 953     Source expression.
 954
 955     Can contain \c NULL.
 956     @endparblock
 957
 958 @bt_pre_assign_expr{_dst}
 959 @bt_pre_assign_expr{_src}
 960 */
 961 #define BT_CLOCK_CLASS_MOVE_REF(_dst, _src)     \
 962         do {                                    \
 963                 bt_clock_class_put_ref(_dst);   \
 964                 (_dst) = (_src);                \
 965                 (_src) = NULL;                  \
 966         } while (0)
 967
 968 /*! @} */
 969
 970 /*! @} */
 971
 972 #ifdef __cplusplus
 973 }
 974 #endif
 975
 976 #endif /* BABELTRACE2_TRACE_IR_CLOCK_CLASS_H */