2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
8 #define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-cs Clock snapshot
29 Snapshot of a \bt_stream clock.
31 A <strong><em>clock snapshot</em></strong> is a snapshot of the value
32 of a \bt_stream clock (a \bt_clock_cls instance).
34 A clock snapshot is a \ref api-tir "trace IR" data object.
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.
41 Instead of having a stream clock object, messages have a default
42 clock snapshot: this is a snapshot of the value of a stream's
43 default clock (a clock class instance):
45 @image html clocks.png
47 In the illustration above, notice that:
49 - Each stream has a default clock (yellow bell alarm clock): this is an
50 instance of the stream's class's default clock class.
51 - Each \bt_msg (objects in blue stream rectangles) created for a given
52 stream has a default clock snapshot (yellow star): this is a snapshot
53 of the stream's default clock.
55 In other words, a default clock snapshot contains the value of the
56 stream's default clock when this message occurred.
58 A clock snapshot is a \ref api-fund-unique-object "unique object": it
61 The type of a clock snapshot is #bt_clock_snapshot.
63 You cannot create a clock snapshot: you specify a clock snapshot value
64 (in clock cycles, a \c uint64_t value) when you create a \bt_msg or set
65 a message's clock snapshot with one of:
67 - bt_message_stream_beginning_set_default_clock_snapshot()
68 - bt_message_stream_end_set_default_clock_snapshot()
69 - bt_message_event_create_with_default_clock_snapshot()
70 - bt_message_event_create_with_packet_and_default_clock_snapshot()
71 - bt_message_packet_beginning_create_with_default_clock_snapshot()
72 - bt_message_packet_end_create_with_default_clock_snapshot()
73 - bt_message_discarded_events_create_with_default_clock_snapshots()
74 - bt_message_discarded_packets_create_with_default_clock_snapshots()
75 - bt_message_message_iterator_inactivity_create()
77 See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
78 to understand the meaning of a clock's value in relation to the
79 properties of its class.
88 @typedef struct bt_clock_snapshot bt_clock_snapshot;
98 Borrows the \ref api-tir-clock-cls "class" of the clock of which
99 \bt_p{clock_snapshot} is a snapshot.
101 @param[in] clock_snapshot
102 Clock snapshot of which to borrow the clock class.
105 \em Borrowed reference of the clock class of \bt_p{clock_snapshot}.
107 @bt_pre_not_null{clock_snapshot}
109 extern const bt_clock_class
*bt_clock_snapshot_borrow_clock_class_const(
110 const bt_clock_snapshot
*clock_snapshot
);
114 Returns the value, in clock cycles, of the clock snapshot
115 \bt_p{clock_snapshot}.
117 @param[in] clock_snapshot
118 Clock snapshot of which to get the value.
121 Value of \bt_p{clock_snapshot} (clock cycles).
123 @bt_pre_not_null{clock_snapshot}
125 @sa bt_clock_snapshot_get_ns_from_origin() —
126 Returns the equivalent nanoseconds from clock class origin of a
127 clock snapshot's value.
129 extern uint64_t bt_clock_snapshot_get_value(
130 const bt_clock_snapshot
*clock_snapshot
);
134 Status codes for bt_clock_snapshot_get_ns_from_origin().
136 typedef enum bt_clock_snapshot_get_ns_from_origin_status
{
141 BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
145 Integer overflow while computing the result.
147 BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
= __BT_FUNC_STATUS_OVERFLOW_ERROR
,
148 } bt_clock_snapshot_get_ns_from_origin_status
;
152 Converts the value of the clock snapshot
153 \bt_p{clock_snapshot} from cycles to nanoseconds from the
154 \ref api-tir-clock-cls-origin "origin" of its
155 \bt_clock_cls and sets \bt_p{*ns_from_origin} to the result.
160 \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
161 property of the clock class of \bt_p{clock_snapshot} to
163 \ref api-tir-clock-cls-prop-freq "frequency".
164 -# Converts the value of \bt_p{clock_snapshot} to seconds using the
165 frequency of its clock class.
166 -# Adds the values of 1., 2., and the
167 \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
168 property of the clock class of \bt_p{clock_snapshot}.
169 -# Converts the value of 3. to nanoseconds and sets
170 \bt_p{*ns_from_origin} to this result.
172 The following illustration shows the possible scenarios:
174 @image html clock-terminology.png
176 This function can fail and return the
177 #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
178 code if any step of the computation process causes an integer overflow.
180 @param[in] clock_snapshot
181 Clock snapshot containing the value to convert to nanoseconds
182 from the origin of its clock class.
183 @param[out] ns_from_origin
184 <strong>On success</strong>, \bt_p{*ns_from_origin} is the value
185 of \bt_p{clock_snapshot} converted to nanoseconds from the origin
188 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
190 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
191 Integer overflow while computing the result.
193 @bt_pre_not_null{clock_snapshot}
194 @bt_pre_not_null{ns_from_origin}
196 @sa bt_util_clock_cycles_to_ns_from_origin() —
197 Converts a clock value from cycles to nanoseconds from the clock's
199 @sa bt_clock_class_cycles_to_ns_from_origin() —
200 Converts a clock value from cycles to nanoseconds from a clock
203 extern bt_clock_snapshot_get_ns_from_origin_status
204 bt_clock_snapshot_get_ns_from_origin(
205 const bt_clock_snapshot
*clock_snapshot
,
206 int64_t *ns_from_origin
);
214 #endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */