include/babeltrace2/trace-ir/clock-class.h

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