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