2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_CLOCK_CLASS_H
8 #define BABELTRACE2_TRACE_IR_CLOCK_CLASS_H
10 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-clock-cls Clock class
27 Class of \bt_stream clocks.
29 A <strong><em>clock class</em></strong> is the class of \bt_stream
32 A clock class is a \ref api-tir "trace IR" metadata object.
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.
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):
43 @image html clocks.png
45 In the illustration above, notice that:
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.
56 In other words, a default clock snapshot contains the value of the
57 stream's default clock when this message occurred.
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.
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().
68 Some library functions \ref api-fund-freezing "freeze" clock classes on
69 success. The documentation of those functions indicate this
72 The type of a clock class is #bt_clock_class.
74 Create a default clock class from a \bt_self_comp with
75 bt_clock_class_create().
77 <h1>\anchor api-tir-clock-cls-origin Clock value vs. clock class origin</h1>
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.
83 A clock class's origin is one of:
86 <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_TRUE</dt>
89 <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
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>,
97 <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_FALSE</dt>
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
108 To compute an effective stream clock value, in cycles from its class's
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
119 Because typical tracer clocks have a high frequency (often 1 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
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).
132 Those functions perform this computation:
134 -# Convert the clock class's "offset in cycles" property to seconds
136 -# Convert the stream clock's value to seconds using the clock class's
138 -# Add the values of 1., 2., and the clock class's "offset in seconds"
140 -# Convert the value of 3. to nanoseconds.
142 The following illustration shows the possible scenarios:
144 @image html clock-terminology.png
146 The clock class's "offset in seconds" property can be negative.
147 For example, considering:
149 - Frequency: 1000 Hz.
150 - Offset in seconds: −10 seconds.
151 - Offset in cycles: 500 cycles (that is, 0.5 seconds).
152 - Stream clock's value: 2000 cycles (that is, 2 seconds).
154 Then the computed value is −7.5 seconds from origin, or
155 −7,500,000,000 nanoseconds from origin.
159 A clock class has the following properties:
162 <dt>\anchor api-tir-clock-cls-prop-freq Frequency</dt>
164 Frequency of the clock class's instances (stream clocks)
167 Use bt_clock_class_set_frequency() and
168 bt_clock_class_get_frequency().
172 \anchor api-tir-clock-cls-prop-offset
173 Offset (in seconds and in cycles)
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).
181 The values of the clock class's instances are relative to the
184 Use bt_clock_class_set_offset() and bt_clock_class_get_offset().
187 <dt>\anchor api-tir-clock-cls-prop-precision Precision</dt>
189 Precision of the clock class's instance (stream clocks) values
192 For example, considering a precision of 7 cycles and the stream
193 clock value 42 cycles, the real stream clock value can be
194 anything between 35 cycles and 49 cycles.
196 Use bt_clock_class_set_precision() and
197 bt_clock_class_get_precision().
201 \anchor api-tir-clock-cls-prop-origin-unix-epoch
202 Origin is Unix epoch?
205 Whether or not the clock class's
206 \ref api-tir-clock-cls-origin "origin"
208 <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
210 Use bt_clock_class_set_origin_is_unix_epoch() and
211 bt_clock_class_origin_is_unix_epoch().
214 <dt>\anchor api-tir-clock-cls-prop-name \bt_dt_opt Name</dt>
216 Name of the clock class.
218 Use bt_clock_class_set_name() and bt_clock_class_get_name().
221 <dt>\anchor api-tir-clock-cls-prop-descr \bt_dt_opt Description</dt>
223 Description of the clock class.
225 Use bt_clock_class_set_description() and
226 bt_clock_class_get_description().
229 <dt>\anchor api-tir-clock-cls-prop-uuid \bt_dt_opt UUID</dt>
231 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
234 The clock class's UUID uniquely identifies the clock class.
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.
241 Use bt_clock_class_set_uuid() and bt_clock_class_get_uuid().
245 \anchor api-tir-clock-cls-prop-user-attrs
246 \bt_dt_opt User attributes
249 User attributes of the clock class.
251 User attributes are custom attributes attached to a clock class.
253 Use bt_clock_class_set_user_attributes(),
254 bt_clock_class_borrow_user_attributes(), and
255 bt_clock_class_borrow_user_attributes_const().
266 @typedef struct bt_clock_class bt_clock_class;
281 Creates a default clock class from the \bt_self_comp
282 \bt_p{self_component}.
284 On success, the returned clock class has the following property values:
291 <td>\ref api-tir-clock-cls-prop-freq "Frequency"
294 <td>\ref api-tir-clock-cls-prop-offset "Offset" in seconds
297 <td>\ref api-tir-clock-cls-prop-offset "Offset" in cycles
300 <td>\ref api-tir-clock-cls-prop-precision "Precision"
303 <td>\ref api-tir-clock-cls-prop-origin-unix-epoch "Origin is Unix epoch?"
306 <td>\ref api-tir-clock-cls-prop-name "Name"
309 <td>\ref api-tir-clock-cls-prop-descr "Description"
312 <td>\ref api-tir-clock-cls-prop-uuid "UUID"
315 <td>\ref api-tir-clock-cls-prop-user-attrs "User attributes"
316 <td>Empty \bt_map_val
319 @param[in] self_component
320 Self component from which to create the default clock class.
323 New clock class reference, or \c NULL on memory error.
325 @bt_pre_not_null{self_component}
327 extern bt_clock_class
*bt_clock_class_create(bt_self_component
*self_component
);
338 Sets the frequency (Hz) of the clock class \bt_p{clock_class} to
341 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
343 @param[in] clock_class
344 Clock class of which to set the frequency to \bt_p{frequency}.
346 New frequency of \bt_p{clock_class}.
348 @bt_pre_not_null{clock_class}
349 @bt_pre_hot{clock_class}
351 \bt_p{frequency} is not 0.
353 \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
355 \bt_p{frequency} is greater than the clock class's offset in cycles
356 (as returned by bt_clock_class_get_offset()).
358 @sa bt_clock_class_get_frequency() —
359 Returns the frequency of a clock class.
361 extern void bt_clock_class_set_frequency(bt_clock_class
*clock_class
,
366 Returns the frequency (Hz) of the clock class \bt_p{clock_class}.
368 See the \ref api-tir-clock-cls-prop-freq "frequency" property.
370 @param[in] clock_class
371 Clock class of which to get the frequency.
374 Frequency (Hz) of \bt_p{clock_class}.
376 @bt_pre_not_null{clock_class}
378 @sa bt_clock_class_set_frequency() —
379 Sets the frequency of a clock class.
381 extern uint64_t bt_clock_class_get_frequency(
382 const bt_clock_class
*clock_class
);
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".
390 See the \ref api-tir-clock-cls-prop-offset "offset" property.
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}.
400 @bt_pre_not_null{clock_class}
401 @bt_pre_hot{clock_class}
403 \bt_p{offset_cycles} is less than the clock class's frequency
404 (as returned by bt_clock_class_get_frequency()).
406 @sa bt_clock_class_get_offset() —
407 Returns the offset of a clock class.
409 extern void bt_clock_class_set_offset(bt_clock_class
*clock_class
,
410 int64_t offset_seconds
, uint64_t offset_cycles
);
414 Returns the offsets in seconds and cycles of the clock class
417 See the \ref api-tir-clock-cls-prop-offset "offset" property.
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
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}.
429 @bt_pre_not_null{clock_class}
430 @bt_pre_not_null{offset_seconds}
431 @bt_pre_not_null{offset_cycles}
433 @sa bt_clock_class_set_offset() —
434 Sets the offset of a clock class.
436 extern void bt_clock_class_get_offset(const bt_clock_class
*clock_class
,
437 int64_t *offset_seconds
, uint64_t *offset_cycles
);
441 Sets the precision (cycles) of the clock class \bt_p{clock_class} to
444 See the \ref api-tir-clock-cls-prop-precision "precision" property.
446 @param[in] clock_class
447 Clock class of which to set the precision to \bt_p{precision}.
449 New precision of \bt_p{clock_class}.
451 @bt_pre_not_null{clock_class}
452 @bt_pre_hot{clock_class}
454 @sa bt_clock_class_get_precision() —
455 Returns the precision of a clock class.
457 extern void bt_clock_class_set_precision(bt_clock_class
*clock_class
,
462 Returns the precision (cycles) of the clock class
465 See the \ref api-tir-clock-cls-prop-precision "precision" property.
467 @param[in] clock_class
468 Clock class of which to get the precision.
471 Precision (cycles) of \bt_p{clock_class}.
473 @bt_pre_not_null{clock_class}
475 @sa bt_clock_class_set_precision() —
476 Sets the precision of a clock class.
478 extern uint64_t bt_clock_class_get_precision(
479 const bt_clock_class
*clock_class
);
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>.
487 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
490 @param[in] clock_class
491 Clock class of which to set whether or not its origin is the
493 @param[in] origin_is_unix_epoch
494 #BT_TRUE to make \bt_p{clock_class} have a Unix epoch origin.
496 @bt_pre_not_null{clock_class}
497 @bt_pre_hot{clock_class}
499 @sa bt_clock_class_origin_is_unix_epoch() —
500 Returns whether or not the origin of a clock class is the
503 extern void bt_clock_class_set_origin_is_unix_epoch(bt_clock_class
*clock_class
,
504 bt_bool origin_is_unix_epoch
);
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>.
512 See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
515 @param[in] clock_class
516 Clock class of which to get whether or not its origin is the
520 #BT_TRUE if the origin of \bt_p{clock_class} is the Unix epoch.
522 @bt_pre_not_null{clock_class}
524 @sa bt_clock_class_set_origin_is_unix_epoch() —
525 Sets whether or not the origin of a clock class is the Unix epoch.
527 extern bt_bool
bt_clock_class_origin_is_unix_epoch(
528 const bt_clock_class
*clock_class
);
532 Status codes for bt_clock_class_set_name().
534 typedef enum bt_clock_class_set_name_status
{
539 BT_CLOCK_CLASS_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
545 BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
546 } bt_clock_class_set_name_status
;
550 Sets the name of the clock class \bt_p{clock_class} to
551 a copy of \bt_p{name}.
553 See the \ref api-tir-clock-cls-prop-name "name" property.
555 @param[in] clock_class
556 Clock class of which to set the name to \bt_p{name}.
558 New name of \bt_p{clock_class} (copied).
560 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_OK
562 @retval #BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
565 @bt_pre_not_null{clock_class}
566 @bt_pre_hot{clock_class}
567 @bt_pre_not_null{name}
569 @sa bt_clock_class_get_name() —
570 Returns the name of a clock class.
572 extern bt_clock_class_set_name_status
bt_clock_class_set_name(
573 bt_clock_class
*clock_class
, const char *name
);
577 Returns the name of the clock class \bt_p{clock_class}.
579 See the \ref api-tir-clock-cls-prop-name "name" property.
581 If \bt_p{clock_class} has no name, this function returns \c NULL.
583 @param[in] clock_class
584 Clock class of which to get the name.
588 Name of \bt_p{clock_class}, or \c NULL if none.
590 The returned pointer remains valid as long as \bt_p{clock_class}
594 @bt_pre_not_null{clock_class}
596 @sa bt_clock_class_set_name() —
597 Sets the name of a clock class.
599 extern const char *bt_clock_class_get_name(
600 const bt_clock_class
*clock_class
);
604 Status codes for bt_clock_class_set_description().
606 typedef enum bt_clock_class_set_description_status
{
611 BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK
= __BT_FUNC_STATUS_OK
,
617 BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
618 } bt_clock_class_set_description_status
;
622 Sets the description of the clock class \bt_p{clock_class} to a copy
623 of \bt_p{description}.
625 See the \ref api-tir-clock-cls-prop-descr "description" property.
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).
632 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK
634 @retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
637 @bt_pre_not_null{clock_class}
638 @bt_pre_hot{clock_class}
639 @bt_pre_not_null{description}
641 @sa bt_clock_class_get_description() —
642 Returns the description of a clock class.
644 extern bt_clock_class_set_description_status
bt_clock_class_set_description(
645 bt_clock_class
*clock_class
, const char *description
);
649 Returns the description of the clock class \bt_p{clock_class}.
651 See the \ref api-tir-clock-cls-prop-descr "description" property.
653 If \bt_p{clock_class} has no description, this function returns \c NULL.
655 @param[in] clock_class
656 Clock class of which to get the description.
660 Description of \bt_p{clock_class}, or \c NULL if none.
662 The returned pointer remains valid as long as \bt_p{clock_class}
666 @bt_pre_not_null{clock_class}
668 @sa bt_clock_class_set_description() —
669 Sets the description of a clock class.
671 extern const char *bt_clock_class_get_description(
672 const bt_clock_class
*clock_class
);
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}.
680 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
682 @param[in] clock_class
683 Clock class of which to set the UUID to \bt_p{uuid}.
685 New UUID of \bt_p{clock_class} (copied).
687 @bt_pre_not_null{clock_class}
688 @bt_pre_hot{clock_class}
689 @bt_pre_not_null{uuid}
691 @sa bt_clock_class_get_uuid() —
692 Returns the UUID of a clock class.
694 extern void bt_clock_class_set_uuid(bt_clock_class
*clock_class
,
699 Returns the UUID of the clock class \bt_p{clock_class}.
701 See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
703 If \bt_p{clock_class} has no UUID, this function returns \c NULL.
705 @param[in] clock_class
706 Clock class of which to get the UUID.
710 UUID of \bt_p{clock_class}, or \c NULL if none.
712 The returned pointer remains valid as long as \bt_p{clock_class}
716 @bt_pre_not_null{clock_class}
718 @sa bt_clock_class_set_uuid() —
719 Sets the UUID of a clock class.
721 extern bt_uuid
bt_clock_class_get_uuid(
722 const bt_clock_class
*clock_class
);
726 Sets the user attributes of the clock class \bt_p{clock_class} to
727 \bt_p{user_attributes}.
729 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
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.
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}.
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}
750 @sa bt_clock_class_borrow_user_attributes() —
751 Borrows the user attributes of a clock class.
753 extern void bt_clock_class_set_user_attributes(
754 bt_clock_class
*clock_class
, const bt_value
*user_attributes
);
758 Borrows the user attributes of the clock class \bt_p{clock_class}.
760 See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
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.
767 @param[in] clock_class
768 Clock class from which to borrow the user attributes.
771 User attributes of \bt_p{clock_class} (a \bt_map_val).
773 @bt_pre_not_null{clock_class}
775 @sa bt_clock_class_set_user_attributes() —
776 Sets the user attributes of a clock class.
777 @sa bt_clock_class_borrow_user_attributes_const() —
778 \c const version of this function.
780 extern bt_value
*bt_clock_class_borrow_user_attributes(
781 bt_clock_class
*clock_class
);
785 Borrows the user attributes of the clock class \bt_p{clock_class}
788 See bt_clock_class_borrow_user_attributes().
790 extern const bt_value
*bt_clock_class_borrow_user_attributes_const(
791 const bt_clock_class
*clock_class
);
802 Status codes for bt_clock_class_cycles_to_ns_from_origin().
804 typedef enum bt_clock_class_cycles_to_ns_from_origin_status
{
809 BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
813 Integer overflow while computing the result.
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
;
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}
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
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.
839 The following illustration shows the possible scenarios:
841 @image html clock-terminology.png
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.
847 @param[in] clock_class
848 Stream clock's class.
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}.
856 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
858 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
859 Integer overflow while computing the result.
861 @bt_pre_not_null{clock_class}
862 @bt_pre_not_null{ns_from_origin}
864 @sa bt_util_clock_cycles_to_ns_from_origin() —
865 Converts a clock value from cycles to nanoseconds from the clock's
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
);
876 @name Reference count
882 Increments the \ref api-fund-shared-object "reference count" of
883 the clock class \bt_p{clock_class}.
885 @param[in] clock_class
887 Clock class of which to increment the reference count.
892 @sa bt_clock_class_put_ref() —
893 Decrements the reference count of a clock class.
895 extern void bt_clock_class_get_ref(const bt_clock_class
*clock_class
);
899 Decrements the \ref api-fund-shared-object "reference count" of
900 the clock class \bt_p{clock_class}.
902 @param[in] clock_class
904 Clock class of which to decrement the reference count.
909 @sa bt_clock_class_get_ref() —
910 Increments the reference count of a clock class.
912 extern void bt_clock_class_put_ref(const bt_clock_class
*clock_class
);
916 Decrements the reference count of the clock class
917 \bt_p{_clock_class}, and then sets \bt_p{_clock_class} to \c NULL.
921 Clock class of which to decrement the reference count.
926 @bt_pre_assign_expr{_clock_class}
928 #define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_clock_class) \
930 bt_clock_class_put_ref(_clock_class); \
931 (_clock_class) = NULL; \
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.
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.
945 Destination expression.
956 @bt_pre_assign_expr{_dst}
957 @bt_pre_assign_expr{_src}
959 #define BT_CLOCK_CLASS_MOVE_REF(_dst, _src) \
961 bt_clock_class_put_ref(_dst); \
974 #endif /* BABELTRACE2_TRACE_IR_CLOCK_CLASS_H */