1 #ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
2 #define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
39 @defgroup api-tir-cs Clock snapshot
43 Snapshot of a \bt_stream clock.
45 A <strong><em>clock snapshot</em></strong> is a snapshot of the value
46 of a \bt_stream clock (a \bt_clock_cls instance).
48 A clock snapshot is a \ref api-tir "trace IR" data object.
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.
55 Instead of having a stream clock object, messages have a default
56 clock snapshot: this is a snapshot of the value of a stream's
57 default clock (a clock class instance):
59 @image html clocks.png
61 In the illustration above, notice that:
63 - Each stream has a default clock (yellow bell alarm clock): this is an
64 instance of the stream's class's default clock class.
65 - Each \bt_msg (objects in blue stream rectangles) created for a given
66 stream has a default clock snapshot (yellow star): this is a snapshot
67 of the stream's default clock.
69 In other words, a default clock snapshot contains the value of the
70 stream's default clock when this message occurred.
72 A clock snapshot is a \ref api-fund-unique-object "unique object": it
75 The type of a clock snapshot is #bt_clock_snapshot.
77 You cannot create a clock snapshot: you specify a clock snapshot value
78 (in clock cycles, a \c uint64_t value) when you create a \bt_msg or set
79 a message's clock snapshot with one of:
81 - bt_message_stream_beginning_set_default_clock_snapshot()
82 - bt_message_stream_end_set_default_clock_snapshot()
83 - bt_message_event_create_with_default_clock_snapshot()
84 - bt_message_event_create_with_packet_and_default_clock_snapshot()
85 - bt_message_packet_beginning_create_with_default_clock_snapshot()
86 - bt_message_packet_end_create_with_default_clock_snapshot()
87 - bt_message_discarded_events_create_with_default_clock_snapshots()
88 - bt_message_discarded_packets_create_with_default_clock_snapshots()
89 - bt_message_message_iterator_inactivity_create()
91 See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
92 to understand the meaning of a clock's value in relation to the
93 properties of its class.
102 @typedef struct bt_clock_snapshot bt_clock_snapshot;
112 Borrows the \ref api-tir-clock-cls "class" of the clock of which
113 \bt_p{clock_snapshot} is a snapshot.
115 @param[in] clock_snapshot
116 Clock snapshot of which to borrow the clock class.
119 \em Borrowed reference of the clock class of \bt_p{clock_snapshot}.
121 @bt_pre_not_null{clock_snapshot}
123 extern const bt_clock_class
*bt_clock_snapshot_borrow_clock_class_const(
124 const bt_clock_snapshot
*clock_snapshot
);
128 Returns the value, in clock cycles, of the clock snapshot
129 \bt_p{clock_snapshot}.
131 @param[in] clock_snapshot
132 Clock snapshot of which to get the value.
135 Value of \bt_p{clock_snapshot} (clock cycles).
137 @bt_pre_not_null{clock_snapshot}
139 @sa bt_clock_snapshot_get_ns_from_origin() —
140 Returns the equivalent nanoseconds from clock class origin of a
141 clock snapshot's value.
143 extern uint64_t bt_clock_snapshot_get_value(
144 const bt_clock_snapshot
*clock_snapshot
);
148 Status codes for bt_clock_snapshot_get_ns_from_origin().
150 typedef enum bt_clock_snapshot_get_ns_from_origin_status
{
155 BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
159 Integer overflow while computing the result.
161 BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
= __BT_FUNC_STATUS_OVERFLOW_ERROR
,
162 } bt_clock_snapshot_get_ns_from_origin_status
;
166 Converts the value of the clock snapshot
167 \bt_p{clock_snapshot} from cycles to nanoseconds from the
168 \ref api-tir-clock-cls-origin "origin" of its
169 \bt_clock_cls and sets \bt_p{*ns_from_origin} to the result.
174 \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
175 property of the clock class of \bt_p{clock_snapshot} to
177 \ref api-tir-clock-cls-prop-freq "frequency".
178 -# Converts the value of \bt_p{clock_snapshot} to seconds using the
179 frequency of its clock class.
180 -# Adds the values of 1., 2., and the
181 \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
182 property of the clock class of \bt_p{clock_snapshot}.
183 -# Converts the value of 3. to nanoseconds and sets
184 \bt_p{*ns_from_origin} to this result.
186 The following illustration shows the possible scenarios:
188 @image html clock-terminology.png
190 This function can fail and return the
191 #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
192 code if any step of the computation process causes an integer overflow.
194 @param[in] clock_snapshot
195 Clock snapshot containing the value to convert to nanoseconds
196 from the origin of its clock class.
197 @param[out] ns_from_origin
198 <strong>On success</strong>, \bt_p{*ns_from_origin} is the value
199 of \bt_p{clock_snapshot} converted to nanoseconds from the origin
202 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
204 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
205 Integer overflow while computing the result.
207 @bt_pre_not_null{clock_snapshot}
208 @bt_pre_not_null{ns_from_origin}
210 @sa bt_util_clock_cycles_to_ns_from_origin() —
211 Converts a clock value from cycles to nanoseconds from the clock's
213 @sa bt_clock_class_cycles_to_ns_from_origin() —
214 Converts a clock value from cycles to nanoseconds from a clock
217 extern bt_clock_snapshot_get_ns_from_origin_status
218 bt_clock_snapshot_get_ns_from_origin(
219 const bt_clock_snapshot
*clock_snapshot
,
220 int64_t *ns_from_origin
);
228 #endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */