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