lib: standardize public include guards
[babeltrace.git] / include / babeltrace2 / ctf-writer / clock.h
CommitLineData
924dc299
PP
1#ifndef BABELTRACE2_CTF_WRITER_CLOCK_H
2#define BABELTRACE2_CTF_WRITER_CLOCK_H
8c18d80b 3
46bd0f2b 4/*
de9dd397 5 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
46bd0f2b
JG
6 *
7 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining a copy
10 * of this software and associated documentation files (the "Software"), to deal
11 * in the Software without restriction, including without limitation the rights
12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 * copies of the Software, and to permit persons to whom the Software is
14 * furnished to do so, subject to the following conditions:
15 *
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
18 *
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 * SOFTWARE.
26 *
27 * The Common Trace Format (CTF) Specification is available at
28 * http://www.efficios.com/ctf
29 */
30
ac0c6bdd 31#include <stdint.h>
3fadfbc0 32#include <babeltrace2/ctf-writer/object.h>
00409097 33#include <babeltrace2/ctf-writer/types.h>
8c18d80b
PP
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
ac0c6bdd 39struct bt_ctf_clock;
3dca2276 40struct bt_ctf_clock_class;
ac0c6bdd
PP
41
42/*
43 * bt_ctf_clock_create: create a clock.
44 *
45 * Allocate a new clock setting its reference count to 1.
46 *
47 * @param name Name of the clock (will be copied); can be set to NULL
48 * for nameless clocks.
49 *
50 * Returns an allocated clock on success, NULL on error.
51 */
52extern struct bt_ctf_clock *bt_ctf_clock_create(const char *name);
53
54/*
55 * bt_ctf_clock_get_name: get a clock's name.
56 *
57 * Get the clock's name.
58 *
59 * @param clock Clock instance.
60 *
61 * Returns the clock's name, NULL on error.
62 */
63extern const char *bt_ctf_clock_get_name(struct bt_ctf_clock *clock);
64
65/*
66 * bt_ctf_clock_get_description: get a clock's description.
67 *
68 * Get the clock's description.
69 *
70 * @param clock Clock instance.
71 *
72 * Returns the clock's description, NULL if unset.
73 */
74extern const char *bt_ctf_clock_get_description(struct bt_ctf_clock *clock);
75
76/*
77 * bt_ctf_clock_set_description: set a clock's description.
78 *
79 * Set the clock's description. The description appears in the clock's TSDL
80 * meta-data.
81 *
82 * @param clock Clock instance.
83 * @param desc Description of the clock.
84 *
85 * Returns 0 on success, a negative value on error.
86 */
87extern int bt_ctf_clock_set_description(struct bt_ctf_clock *clock,
88 const char *desc);
89
90/*
91 * bt_ctf_clock_get_frequency: get a clock's frequency.
92 *
93 * Get the clock's frequency (Hz).
94 *
95 * @param clock Clock instance.
96 *
97 * Returns the clock's frequency, -1ULL on error.
98 */
99extern uint64_t bt_ctf_clock_get_frequency(struct bt_ctf_clock *clock);
100
101/*
102 * bt_ctf_clock_set_frequency: set a clock's frequency.
103 *
104 * Set the clock's frequency (Hz).
105 *
106 * @param clock Clock instance.
107 * @param freq Clock's frequency in Hz, defaults to 1 000 000 000 Hz (1ns).
108 *
109 * Returns 0 on success, a negative value on error.
110 */
111extern int bt_ctf_clock_set_frequency(struct bt_ctf_clock *clock,
112 uint64_t freq);
113
114/*
115 * bt_ctf_clock_get_precision: get a clock's precision.
116 *
117 * Get the clock's precision (in clock ticks).
118 *
119 * @param clock Clock instance.
120 *
121 * Returns the clock's precision, -1ULL on error.
122 */
123extern uint64_t bt_ctf_clock_get_precision(struct bt_ctf_clock *clock);
124
125/*
126 * bt_ctf_clock_set_precision: set a clock's precision.
127 *
128 * Set the clock's precision.
129 *
130 * @param clock Clock instance.
131 * @param precision Clock's precision in clock ticks, defaults to 1.
132 *
133 * Returns 0 on success, a negative value on error.
134 */
135extern int bt_ctf_clock_set_precision(struct bt_ctf_clock *clock,
136 uint64_t precision);
137
138/*
139 * bt_ctf_clock_get_offset_s: get a clock's offset in seconds.
140 *
141 * Get the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01.
142 *
143 * @param clock Clock instance.
144 * @param offset_s Pointer to clock offset in seconds (output).
145 *
146 * Returns 0 on success, a negative value on error.
147 */
148extern int bt_ctf_clock_get_offset_s(struct bt_ctf_clock *clock,
149 int64_t *offset_s);
150
151/*
152 * bt_ctf_clock_set_offset_s: set a clock's offset in seconds.
153 *
154 * Set the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01,
155 * defaults to 0.
156 *
157 * @param clock Clock instance.
158 * @param offset_s Clock's offset in seconds, defaults to 0.
159 *
160 * Returns 0 on success, a negative value on error.
161 */
162extern int bt_ctf_clock_set_offset_s(struct bt_ctf_clock *clock,
163 int64_t offset_s);
164
165/*
166 * bt_ctf_clock_get_offset: get a clock's offset in ticks.
167 *
168 * Get the clock's offset in ticks from Epoch + offset_t.
169 *
170 * @param clock Clock instance.
171 * @param offset Clock offset in ticks from Epoch + offset_s (output).
172 *
173 * Returns 0 on success, a negative value on error.
174 */
175extern int bt_ctf_clock_get_offset(struct bt_ctf_clock *clock,
176 int64_t *offset);
177
178/*
179 * bt_ctf_clock_set_offset: set a clock's offset in ticks.
180 *
181 * Set the clock's offset in ticks from Epoch + offset_s.
182 *
183 * @param clock Clock instance.
184 * @param offset Clock's offset in ticks from Epoch + offset_s, defaults to 0.
185 *
186 * Returns 0 on success, a negative value on error.
187 */
188extern int bt_ctf_clock_set_offset(struct bt_ctf_clock *clock,
189 int64_t offset);
190
191/*
192 * bt_ctf_clock_get_is_absolute: get a clock's absolute attribute.
193 *
194 * Get the clock's absolute attribute. A clock is absolute if the clock is a
195 * global reference across the trace's other clocks.
196 *
197 * @param clock Clock instance.
198 *
199 * Returns the clock's absolute attribute, a negative value on error.
200 */
201extern int bt_ctf_clock_get_is_absolute(struct bt_ctf_clock *clock);
202
203/*
204 * bt_ctf_clock_set_is_absolute: set a clock's absolute attribute.
205 *
206 * Set the clock's absolute attribute. A clock is absolute if the clock is a
207 * global reference across the trace's other clocks.
208 *
209 * @param clock Clock instance.
210 * @param is_absolute Clock's absolute attribute, defaults to FALSE.
211 *
212 * Returns 0 on success, a negative value on error.
213 */
214extern int bt_ctf_clock_set_is_absolute(struct bt_ctf_clock *clock,
215 int is_absolute);
216
217/*
218 * bt_ctf_clock_get_uuid: get a clock's UUID.
219 *
220 * Get the clock's UUID.
221 *
222 * @param clock Clock instance.
223 *
224 * Returns a pointer to the clock's UUID (16 byte array) on success,
225 * NULL on error.
226 */
6162e6b7 227extern const uint8_t *bt_ctf_clock_get_uuid(struct bt_ctf_clock *clock);
ac0c6bdd
PP
228
229/*
230 * bt_ctf_clock_set_uuid: set a clock's UUID.
231 *
232 * Set a clock's UUID.
233 *
234 * @param clock Clock instance.
235 * @param uuid A 16-byte array containing a UUID.
236 *
237 * Returns 0 on success, a negative value on error.
238 */
239extern int bt_ctf_clock_set_uuid(struct bt_ctf_clock *clock,
6162e6b7 240 const uint8_t *uuid);
ac0c6bdd 241
64cf1d3a
PP
242/*
243 * bt_ctf_clock_set_time: set a clock's current time value.
244 *
245 * Set the current time in nanoseconds since the clock's origin (offset and
246 * offset_s attributes). Defaults to 0.
247 *
248 * Returns 0 on success, a negative value on error.
249 */
250extern int bt_ctf_clock_set_time(struct bt_ctf_clock *clock,
251 int64_t time);
252
8c18d80b
PP
253/*
254 * bt_ctf_clock_get and bt_ctf_clock_put: increment and decrement the
255 * refcount of the clock
256 *
257 * You may also use bt_ctf_get() and bt_ctf_put() with clock objects.
258 *
259 * These functions ensure that the clock won't be destroyed when it
260 * is in use. The same number of get and put (plus one extra put to
261 * release the initial reference done at creation) has to be done to
262 * destroy a clock.
263 *
264 * When the clock refcount is decremented to 0 by a bt_ctf_clock_put,
265 * the clock is freed.
266 *
267 * @param clock Clock instance.
268 */
3dca2276
PP
269
270/* Pre-2.0 CTF writer compatibility */
271static inline
272void bt_ctf_clock_get(struct bt_ctf_clock *clock)
273{
e1e02a22 274 bt_ctf_object_get_ref(clock);
3dca2276
PP
275}
276
277/* Pre-2.0 CTF writer compatibility */
278static inline
279void bt_ctf_clock_put(struct bt_ctf_clock *clock)
280{
e1e02a22 281 bt_ctf_object_put_ref(clock);
3dca2276 282}
8c18d80b
PP
283#ifdef __cplusplus
284}
285#endif
286
924dc299 287#endif /* BABELTRACE2_CTF_WRITER_CLOCK_H */
This page took 0.068623 seconds and 4 git commands to generate.