949672266188b879f6faabe658d82c1890312a8b
[babeltrace.git] / include / babeltrace / ctf-ir / trace.h
1 #ifndef BABELTRACE_CTF_IR_TRACE_H
2 #define BABELTRACE_CTF_IR_TRACE_H
3
4 /*
5 * BabelTrace - CTF IR: Trace
6 *
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 *
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
31 */
32
33 /* For bt_get() */
34 #include <babeltrace/ref.h>
35
36 /* For bt_visitor */
37 #include <babeltrace/ctf-ir/visitor.h>
38
39 /* For bt_bool */
40 #include <babeltrace/types.h>
41 #include <stdint.h>
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /**
48 @defgroup ctfirtraceclass CTF IR trace class
49 @ingroup ctfir
50 @brief CTF IR trace class.
51
52 @code
53 #include <babeltrace/ctf-ir/trace.h>
54 @endcode
55
56 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
57 traces.
58
59 You can obtain a trace class in two different modes:
60
61 - <strong>Normal mode</strong>: use bt_trace_create() to create a
62 default, empty trace class.
63 - <strong>CTF writer mode</strong>: use bt_writer_get_trace() to
64 get the trace class created by a given CTF writer object.
65
66 A trace class has the following properties:
67
68 - A \b name.
69 - A <strong>native byte order</strong>: all the
70 \link ctfirfieldtypes field types\endlink eventually part of the trace
71 class with a byte order set to #BT_BYTE_ORDER_NATIVE have this
72 "real" byte order.
73 - A \b UUID.
74 - An \b environment, which is a custom key-value mapping. Keys are
75 strings and values can be strings or integers.
76
77 In the Babeltrace CTF IR system, a trace class contains zero or more
78 \link ctfirstreamclass stream classes\endlink, and a stream class
79 contains zero or more \link ctfireventclass event classes\endlink. You
80 can add an event class to a stream class with
81 bt_stream_class_add_event_class(). You can add a stream class to a
82 trace class with bt_trace_add_stream_class().
83
84 You can access the streams of a trace, that is, the streams which were
85 created from the trace's stream classes with bt_stream_create(),
86 with bt_trace_get_stream_by_index().
87
88 A trace class owns the <strong>trace packet header</strong>
89 \link ctfirfieldtypes field type\endlink, which represents the
90 \c trace.packet.header CTF scope. This field type describes the
91 trace packet header fields of the traces that this trace class
92 describes.
93
94 The trace packet header field type \em must be a structure field type as
95 of Babeltrace \btversion.
96
97 As per the CTF specification, the trace packet header field type \em
98 must contain a field named \c stream_id if the trace class contains more
99 than one stream class.
100
101 As a reminder, here's the structure of a CTF packet:
102
103 @imgpacketstructure
104
105 A trace class also contains zero or more
106 \link ctfirclockclass CTF IR clock classes\endlink.
107
108 @todo
109 Elaborate about clock classes irt clock values.
110
111 As with any Babeltrace object, CTF IR trace class objects have
112 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
113 counts</a>. See \ref refs to learn more about the reference counting
114 management of Babeltrace objects.
115
116 The following functions \em freeze their trace class parameter on
117 success:
118
119 - bt_trace_add_stream_class()
120 - bt_writer_create_stream()
121 (\link ctfwriter CTF writer\endlink mode only)
122
123 You cannot modify a frozen trace class: it is considered immutable,
124 except for:
125
126 - Adding a stream class to it with
127 bt_trace_add_stream_class().
128 - Adding a CTF IR clock class to it with bt_trace_add_clock_class().
129 - \link refs Reference counting\endlink.
130
131 @sa ctfirstreamclass
132 @sa ctfireventclass
133 @sa ctfirclockclass
134
135 @file
136 @brief CTF IR trace class type and functions.
137 @sa ctfirtraceclass
138
139 @addtogroup ctfirtraceclass
140 @{
141 */
142
143 /**
144 @struct bt_trace
145 @brief A CTF IR trace class.
146 @sa ctfirtraceclass
147 */
148 struct bt_trace;
149 struct bt_stream;
150 struct bt_stream_class;
151 struct bt_clock_class;
152 struct bt_field_type;
153 struct bt_value;
154 struct bt_packet_header_field;
155
156 /**
157 @brief User function type to use with
158 bt_trace_add_is_static_listener().
159
160 @param[in] trace_class Trace class which is now static.
161 @param[in] data User data as passed to
162 bt_trace_add_is_static_listener() when
163 you added the listener.
164
165 @prenotnull{trace_class}
166 */
167 typedef void (* bt_trace_is_static_listener)(
168 struct bt_trace *trace_class, void *data);
169
170 /**
171 @brief User function type to use with
172 bt_trace_add_is_static_listener().
173
174 @param[in] trace_class Trace class to which the listener was added.
175 @param[in] data User data as passed to
176 bt_trace_add_is_static_listener() when
177 you added the listener.
178
179 @prenotnull{trace_class}
180 */
181 typedef void (* bt_trace_listener_removed)(
182 struct bt_trace *trace_class, void *data);
183
184 /**
185 @name Creation function
186 @{
187 */
188
189 /**
190 @brief Creates a default CTF IR trace class.
191
192 On success, the trace packet header field type of the created trace
193 class is an empty structure field type. You can modify this default
194 trace packet header field type after the trace class is created with
195 bt_trace_get_packet_header_field_type() and
196 bt_trace_set_packet_header_field_type().
197
198 The created trace class has the following initial properties:
199
200 - <strong>Name</strong>: none. You can set a name
201 with bt_trace_set_name().
202 - <strong>UUID</strong>: none. You can set a UUID with
203 bt_trace_set_uuid().
204 - <strong>Native byte order</strong>: #BT_BYTE_ORDER_UNSPECIFIED.
205 You can set a native byte order with
206 bt_trace_set_native_byte_order().
207 - <strong>Environment</strong>: empty. You can add environment entries
208 with bt_trace_set_environment_field(),
209 bt_trace_set_environment_field_integer(), and
210 bt_trace_set_environment_field_string().
211
212 @returns Created trace class, or \c NULL on error.
213
214 @postsuccessrefcountret1
215 */
216 extern struct bt_trace *bt_trace_create(void);
217
218 /** @} */
219
220 /**
221 @name Properties functions
222 @{
223 */
224
225 /**
226 @brief Returns the name of the CTF IR trace class \p trace_class.
227
228 On success, \p trace_class remains the sole owner of the returned
229 string. The returned string is valid as long as \p trace_class exists
230 and is not modified.
231
232 @param[in] trace_class Trace class of which to get the name.
233 @returns Name of trace class \p trace_class, or
234 \c NULL if \p trace_class is unnamed or
235 on error.
236
237 @prenotnull{trace_class}
238 @postrefcountsame{trace_class}
239
240 @sa bt_trace_set_name(): Sets the name of a given trace class.
241 */
242 extern const char *bt_trace_get_name(struct bt_trace *trace_class);
243
244 /**
245 @brief Sets the name of the CTF IR trace class \p trace_class
246 to \p name.
247
248 @param[in] trace_class Trace class of which to set the name.
249 @param[in] name Name of the trace class (copied on success).
250 @returns 0 on success, or a negative value on error.
251
252 @prenotnull{trace_class}
253 @prenotnull{name}
254 @prehot{trace_class}
255 @postrefcountsame{trace_class}
256
257 @sa bt_trace_get_name(): Returns the name of a given trace class.
258 */
259 extern int bt_trace_set_name(struct bt_trace *trace_class,
260 const char *name);
261
262 /**
263 @brief Returns the native byte order of the CTF IR trace class
264 \p trace_class.
265
266 @param[in] trace_class Trace class of which to get the default byte
267 order.
268 @returns Native byte order of \p trace_class,
269 or #BT_BYTE_ORDER_UNKNOWN on error.
270
271 @prenotnull{trace_class}
272 @postrefcountsame{trace_class}
273
274 @sa bt_trace_set_native_byte_order(): Sets the native byte order of
275 a given trace class.
276 */
277 extern enum bt_byte_order bt_trace_get_native_byte_order(
278 struct bt_trace *trace_class);
279
280 /**
281 @brief Sets the native byte order of the CTF IR trace class
282 \p trace_class to \p native_byte_order.
283
284 \p native_byte_order \em must be one of:
285
286 - #BT_BYTE_ORDER_LITTLE_ENDIAN
287 - #BT_BYTE_ORDER_BIG_ENDIAN
288 - #BT_BYTE_ORDER_NETWORK
289 - <strong>If the trace is not in CTF writer mode<strong>,
290 #BT_BYTE_ORDER_UNSPECIFIED.
291
292 @param[in] trace_class Trace class of which to set the native byte
293 order.
294 @param[in] native_byte_order Native byte order of the trace class.
295 @returns 0 on success, or a negative value on error.
296
297 @prenotnull{trace_class}
298 @prehot{trace_class}
299 @pre \p native_byte_order is either #BT_BYTE_ORDER_UNSPECIFIED (if the
300 trace is not in CTF writer mode),
301 #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN, or
302 #BT_BYTE_ORDER_NETWORK.
303 @postrefcountsame{trace_class}
304
305 @sa bt_trace_get_native_byte_order(): Returns the native byte order of a
306 given trace class.
307 */
308 extern int bt_trace_set_native_byte_order(struct bt_trace *trace_class,
309 enum bt_byte_order native_byte_order);
310
311 /**
312 @brief Returns the UUID of the CTF IR trace class \p trace_class.
313
314 On success, the return value is an array of 16 bytes.
315
316 @param[in] trace_class Trace class of which to get the UUID.
317 @returns UUID of trace class \p trace_class, or
318 \c NULL if \p trace_class has no UUID or on error.
319
320 @prenotnull{trace_class}
321 @postrefcountsame{trace_class}
322
323 @sa bt_trace_set_uuid(): Sets the UUID of a given trace class.
324 */
325 extern const unsigned char *bt_trace_get_uuid(
326 struct bt_trace *trace_class);
327
328 /**
329 @brief Sets the UUID of the CTF IR trace class \p trace_class to
330 \p uuid.
331
332 \p uuid \em must be an array of 16 bytes.
333
334 @param[in] trace_class Trace class of which to set the UUID.
335 @param[in] uuid UUID of the \p trace_class (copied on
336 success).
337 @returns 0 on success, or a negative value on error.
338
339 @prenotnull{trace_class}
340 @prenotnull{uuid}
341 @prehot{trace_class}
342 @pre \p uuid is an array of 16 bytes.
343 @postrefcountsame{trace_class}
344
345 @sa bt_trace_get_uuid(): Returns the UUID of a given trace class.
346 */
347 extern int bt_trace_set_uuid(struct bt_trace *trace_class,
348 const unsigned char *uuid);
349
350 /**
351 @brief Returns the number of entries contained in the environment of
352 the CTF IR trace class \p trace_class.
353
354 @param[in] trace_class Trace class of which to get the number
355 of environment entries.
356 @returns Number of environment entries
357 contained in \p trace_class, or
358 a negative value on error.
359
360 @prenotnull{trace_class}
361 @postrefcountsame{trace_class}
362 */
363 extern int64_t bt_trace_get_environment_field_count(
364 struct bt_trace *trace_class);
365
366 /**
367 @brief Returns the field name of the environment entry at index
368 \p index in the CTF IR trace class \p trace_class.
369
370 On success, the returned string is valid as long as this trace class
371 exists and is \em not modified. \p trace_class remains the sole owner of
372 the returned string.
373
374 @param[in] trace_class Trace class of which to get the name of the
375 environment entry at index \p index.
376 @param[in] index Index of environment entry to find.
377 @returns Name of the environment entry at index \p index
378 in \p trace_class, or \c NULL on error.
379
380 @prenotnull{trace_class}
381 @pre \p index is lesser than the number of environment entries in
382 \p trace_class (see bt_trace_get_environment_field_count()).
383 @postrefcountsame{trace_class}
384
385 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
386 environment entry by index.
387 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
388 class's environment entry by name.
389 @sa bt_trace_set_environment_field(): Sets the value of a trace
390 class's environment entry.
391 */
392 extern const char *
393 bt_trace_get_environment_field_name_by_index(
394 struct bt_trace *trace_class, uint64_t index);
395
396 extern struct bt_value *
397 bt_trace_borrow_environment_field_value_by_index(struct bt_trace *trace_class,
398 uint64_t index);
399
400 /**
401 @brief Returns the value of the environment entry at index
402 \p index in the CTF IR trace class \p trace_class.
403
404 @param[in] trace_class Trace class of which to get the value of the
405 environment entry at index \p index.
406 @param[in] index Index of the environment entry to find.
407 @returns Value of the environment entry at index \p index
408 in \p trace_class, or \c NULL on error.
409
410 @prenotnull{trace_class}
411 @pre \p index is lesser than the number of environment entries in
412 \p trace_class (see bt_trace_get_environment_field_count()).
413 @postrefcountsame{trace_class}
414 @postsuccessrefcountretinc
415
416 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
417 class's environment entry by name.
418 @sa bt_trace_set_environment_field(): Sets the value of a trace
419 class's environment entry.
420 */
421 static inline
422 struct bt_value *bt_trace_get_environment_field_value_by_index(
423 struct bt_trace *trace_class, uint64_t index)
424 {
425 return bt_get(bt_trace_borrow_environment_field_value_by_index(
426 trace_class, index));
427 }
428
429 extern struct bt_value *
430 bt_trace_borrow_environment_field_value_by_name(
431 struct bt_trace *trace_class, const char *name);
432
433 /**
434 @brief Returns the value of the environment entry named \p name
435 in the CTF IR trace class \p trace_class.
436
437 @param[in] trace_class Trace class of which to get the value of the
438 environment entry named \p name.
439 @param[in] name Name of the environment entry to find.
440 @returns Value of the environment entry named \p name
441 in \p trace_class, or \c NULL if there's no such
442 entry or on error.
443
444 @prenotnull{trace_class}
445 @prenotnull{name}
446 @postrefcountsame{trace_class}
447 @postsuccessrefcountretinc
448
449 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
450 environment entry by index.
451 @sa bt_trace_set_environment_field(): Sets the value of a trace
452 class's environment entry.
453 */
454 static inline
455 struct bt_value *
456 bt_trace_get_environment_field_value_by_name(
457 struct bt_trace *trace_class, const char *name)
458 {
459 return bt_get(
460 bt_trace_borrow_environment_field_value_by_name(
461 trace_class, name));
462 }
463
464 /**
465 @brief Sets the environment entry named \p name in the
466 CTF IR trace class \p trace_class to \p value.
467
468 If an environment entry named \p name exists in \p trace_class, its
469 value is first put, and then replaced by \p value.
470
471 @param[in] trace_class Trace class of which to set the environment
472 entry.
473 @param[in] name Name of the environment entry to set (copied
474 on success).
475 @param[in] value Value of the environment entry named \p name.
476 @returns 0 on success, or a negative value on error.
477
478 @prenotnull{trace_class}
479 @prenotnull{name}
480 @prenotnull{value}
481 @prehot{trace_class}
482 @pre \p value is an
483 \link bt_value_integer_create() integer value object\endlink
484 or a
485 \link bt_value_string_create() string value object\endlink.
486 @postrefcountsame{trace_class}
487 @postsuccessrefcountinc{value}
488
489 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
490 environment entry by index.
491 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
492 class's environment entry by name.
493 */
494 extern int bt_trace_set_environment_field(
495 struct bt_trace *trace_class, const char *name,
496 struct bt_value *value);
497
498 /**
499 @brief Sets the environment entry named \p name in the
500 CTF IR trace class \p trace_class to \p value.
501
502 If an environment entry named \p name exists in \p trace_class, its
503 value is first put, and then replaced by a new
504 \link bt_value_integer_create() integer value object\endlink
505 containing \p value.
506
507 @param[in] trace_class Trace class of which to set the environment
508 entry.
509 @param[in] name Name of the environment entry to set (copied
510 on success).
511 @param[in] value Value of the environment entry named \p name.
512 @returns 0 on success, or a negative value on error.
513
514 @prenotnull{trace_class}
515 @prenotnull{name}
516 @prehot{trace_class}
517 @postrefcountsame{trace_class}
518
519 @sa bt_trace_set_environment_field(): Sets the value of a trace
520 class's environment entry.
521 */
522 extern int bt_trace_set_environment_field_integer(
523 struct bt_trace *trace_class, const char *name,
524 int64_t value);
525
526 /**
527 @brief Sets the environment entry named \p name in the
528 CTF IR trace class \p trace_class to \p value.
529
530 If an environment entry named \p name exists in \p trace_class, its
531 value is first put, and then replaced by a new
532 \link bt_value_string_create() string value object\endlink
533 containing \p value.
534
535 @param[in] trace_class Trace class of which to set the environment
536 entry.
537 @param[in] name Name of the environment entry to set (copied
538 on success).
539 @param[in] value Value of the environment entry named \p name
540 (copied on success).
541 @returns 0 on success, or a negative value on error.
542
543 @prenotnull{trace_class}
544 @prenotnull{name}
545 @prenotnull{value}
546 @prehot{trace_class}
547 @postrefcountsame{trace_class}
548
549 @sa bt_trace_set_environment_field(): Sets the value of a trace
550 class's environment entry.
551 */
552 extern int bt_trace_set_environment_field_string(
553 struct bt_trace *trace_class, const char *name,
554 const char *value);
555
556 /** @} */
557
558 /**
559 @name Contained field types functions
560 @{
561 */
562
563 extern struct bt_field_type *bt_trace_borrow_packet_header_field_type(
564 struct bt_trace *trace_class);
565
566 /**
567 @brief Returns the packet header field type of the CTF IR trace class
568 \p trace_class.
569
570 @param[in] trace_class Trace class of which to get the packet
571 header field type.
572 @returns Packet header field type of \p trace_class,
573 or \c NULL if \p trace_class has no packet header field
574 type or on error.
575
576 @prenotnull{trace_class}
577 @postrefcountsame{trace_class}
578 @post <strong>On success, if the return value is a field type</strong>, its
579 reference count is incremented.
580
581 @sa bt_trace_set_packet_header_field_type(): Sets the packet
582 header field type of a given trace class.
583 */
584 static inline
585 struct bt_field_type *bt_trace_get_packet_header_field_type(
586 struct bt_trace *trace_class)
587 {
588 return bt_get(bt_trace_borrow_packet_header_field_type(trace_class));
589 }
590
591 extern struct bt_packet_header_field *bt_trace_create_packet_header_field(
592 struct bt_trace *trace);
593
594 /**
595 @brief Sets the packet header field type of the CTF IR trace class
596 \p trace_class to \p packet_header_type, or unsets the current packet
597 header field type from \p trace_class.
598
599 If \p packet_header_type is \c NULL, then this function unsets the current
600 packet header field type from \p trace_class, effectively making \p trace_class
601 a trace without a packet header field type.
602
603 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
604 \p packet_header_type \em must be a CTF IR structure field type object.
605
606 @param[in] trace_class Trace class of which to set the packet
607 header field type.
608 @param[in] packet_header_type Packet header field type, or \c NULL to unset
609 the current packet header field type.
610 @returns 0 on success, or a negative value on error.
611
612 @prenotnull{trace_class}
613 @prehot{trace_class}
614 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
615 structure field type.
616 @postrefcountsame{trace_class}
617 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
618 the reference count of \p packet_header_type is incremented.
619
620 @sa bt_trace_get_packet_header_field_type(): Returns the packet
621 header field type of a given trace class.
622 */
623 extern int bt_trace_set_packet_header_field_type(struct bt_trace *trace_class,
624 struct bt_field_type *packet_header_type);
625
626 /** @} */
627
628 /**
629 @name Contained clock classes functions
630 @{
631 */
632
633 /**
634 @brief Returns the number of CTF IR clock classes contained in the
635 CTF IR trace class \p trace_class.
636
637 @param[in] trace_class Trace class of which to get the number
638 of contained clock classes.
639 @returns Number of contained clock classes
640 contained in \p trace_class, or a negative
641 value on error.
642
643 @prenotnull{trace_class}
644 @postrefcountsame{trace_class}
645 */
646 extern int64_t bt_trace_get_clock_class_count(
647 struct bt_trace *trace_class);
648
649 extern struct bt_clock_class *bt_trace_borrow_clock_class_by_index(
650 struct bt_trace *trace_class, uint64_t index);
651
652 /**
653 @brief Returns the CTF IR clock class at index \p index in the CTF
654 IR trace class \p trace_class.
655
656 @param[in] trace_class Trace class of which to get the clock class
657 contained at index \p index.
658 @param[in] index Index of the clock class to find in
659 \p trace_class.
660 @returns Clock class at index \p index in \p trace_class,
661 or \c NULL on error.
662
663 @prenotnull{trace_class}
664 @pre \p index is lesser than the number of clock classes contained in
665 the trace class \p trace_class (see
666 bt_trace_get_clock_class_count()).
667 @postrefcountsame{trace_class}
668 @postsuccessrefcountretinc
669
670 @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name
671 in a given trace class.
672 @sa bt_trace_add_clock_class(): Adds a clock class to a trace class.
673 */
674 static inline
675 struct bt_clock_class *bt_trace_get_clock_class_by_index(
676 struct bt_trace *trace_class, uint64_t index)
677 {
678 return bt_get(bt_trace_borrow_clock_class_by_index(
679 trace_class, index));
680 }
681
682 extern struct bt_clock_class *bt_trace_borrow_clock_class_by_name(
683 struct bt_trace *trace_class, const char *name);
684
685 /**
686 @brief Returns the CTF IR clock class named \c name found in the CTF
687 IR trace class \p trace_class.
688
689 @param[in] trace_class Trace class of which to get the clock class
690 named \p name.
691 @param[in] name Name of the clock class to find in \p trace_class.
692 @returns Clock class named \p name in \p trace_class,
693 or \c NULL on error.
694
695 @prenotnull{trace_class}
696 @prenotnull{name}
697 @postrefcountsame{trace_class}
698 @postsuccessrefcountretinc
699
700 @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained
701 in a given trace class at a given index.
702 @sa bt_trace_add_clock_class(): Adds a clock class to a trace class.
703 */
704 static inline
705 struct bt_clock_class *bt_trace_get_clock_class_by_name(
706 struct bt_trace *trace_class, const char *name)
707 {
708 return bt_get(bt_trace_borrow_clock_class_by_name(trace_class, name));
709 }
710
711 /**
712 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
713 trace class \p trace_class.
714
715 On success, \p trace_class contains \p clock_class.
716
717 You can call this function even if \p trace_class or \p clock_class
718 are frozen.
719
720 @param[in] trace_class Trace class to which to add \p clock_class.
721 @param[in] clock_class Clock class to add to \p trace_class.
722 @returns 0 on success, or a negative value on error.
723
724 @prenotnull{trace_class}
725 @prenotnull{clock_class}
726 @postrefcountsame{trace_class}
727 @postsuccessrefcountinc{clock_class}
728 @post <strong>On success, if \p trace_class is frozen</strong>,
729 \p clock_class is frozen.
730
731 @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained
732 in a given trace class at a given index.
733 @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name
734 in a given trace class.
735 */
736 extern int bt_trace_add_clock_class(struct bt_trace *trace_class,
737 struct bt_clock_class *clock_class);
738
739 /** @} */
740
741 /**
742 @name Stream class children functions
743 @{
744 */
745
746 /**
747 @brief Returns the number of stream classes contained in the
748 CTF IR trace class \p trace_class.
749
750 @param[in] trace_class Trace class of which to get the number
751 of children stream classes.
752 @returns Number of children stream classes
753 contained in \p trace_class, or a negative
754 value on error.
755
756 @prenotnull{trace_class}
757 @postrefcountsame{trace_class}
758 */
759 extern int64_t bt_trace_get_stream_class_count(
760 struct bt_trace *trace_class);
761
762 extern struct bt_stream_class *bt_trace_borrow_stream_class_by_index(
763 struct bt_trace *trace_class, uint64_t index);
764
765 /**
766 @brief Returns the stream class at index \p index in the CTF IR trace
767 class \p trace_class.
768
769 @param[in] trace_class Trace class of which to get the stream class.
770 @param[in] index Index of the stream class to find.
771 @returns Stream class at index \p index, or \c NULL
772 on error.
773
774 @prenotnull{trace_class}
775 @pre \p index is lesser than the number of stream classes contained in
776 the trace class \p trace_class (see
777 bt_trace_get_stream_class_count()).
778 @postrefcountsame{trace_class}
779
780 @sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID.
781 @sa bt_trace_add_stream_class(): Adds a stream class to a trace class.
782 */
783 static inline
784 struct bt_stream_class *bt_trace_get_stream_class_by_index(
785 struct bt_trace *trace_class, uint64_t index)
786 {
787 return bt_get(bt_trace_borrow_stream_class_by_index(
788 trace_class, index));
789 }
790
791 extern struct bt_stream_class *bt_trace_borrow_stream_class_by_id(
792 struct bt_trace *trace_class, uint64_t id);
793
794 /**
795 @brief Returns the stream class with ID \c id found in the CTF IR
796 trace class \p trace_class.
797
798 @param[in] trace_class Trace class of which to get the stream class.
799 @param[in] id ID of the stream class to find.
800 @returns Stream class with ID \p id, or \c NULL
801 on error.
802
803 @prenotnull{trace_class}
804 @postrefcountsame{trace_class}
805 @postsuccessrefcountretinc
806
807 @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained
808 in a given trace class at a given index.
809 @sa bt_trace_add_stream_class(): Adds a stream class to a trace class.
810 */
811 static inline
812 struct bt_stream_class *bt_trace_get_stream_class_by_id(
813 struct bt_trace *trace_class, uint64_t id)
814 {
815 return bt_get(bt_trace_borrow_stream_class_by_id(trace_class, id));
816 }
817
818 /**
819 @brief Adds the CTF IR stream class \p stream_class to the
820 CTF IR trace class \p trace_class.
821
822 On success, \p stream_class becomes the child of \p trace_class.
823
824 You can only add a given stream class to one trace class.
825
826 You can call this function even if \p trace_class is frozen.
827
828 This function tries to resolve the needed
829 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
830 types that are found anywhere in the root field types of
831 \p stream_class and of all its currently contained
832 \link ctfireventclass CTF IR event classes\endlink. If any automatic
833 resolving fails, then this function fails.
834
835 @param[in] trace_class Trace class to which to add \p stream_class.
836 @param[in] stream_class Stream class to add to \p trace_class.
837 @returns 0 on success, or a negative value on error.
838
839 @prenotnull{trace_class}
840 @prenotnull{stream_class}
841 @postrefcountsame{trace_class}
842 @postsuccessrefcountinc{stream_class}
843 @postsuccessfrozen{stream_class}
844
845 @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained
846 in a given trace class at a given index.
847 @sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID.
848 */
849 extern int bt_trace_add_stream_class(struct bt_trace *trace_class,
850 struct bt_stream_class *stream_class);
851
852 /** @} */
853
854 /**
855 @name Stream children functions
856 @{
857 */
858
859 /**
860 @brief Returns the number of streams contained in the CTF IR trace
861 class \p trace_class.
862
863 @param[in] trace_class Trace class of which to get the number
864 of children streams.
865 @returns Number of children streams
866 contained in \p trace_class, or a negative
867 value on error.
868
869 @prenotnull{trace_class}
870 @postrefcountsame{trace_class}
871 */
872 extern int64_t bt_trace_get_stream_count(struct bt_trace *trace_class);
873
874 extern struct bt_stream *bt_trace_borrow_stream_by_index(
875 struct bt_trace *trace_class, uint64_t index);
876
877 /**
878 @brief Returns the stream at index \p index in the CTF IR trace
879 class \p trace_class.
880
881 @param[in] trace_class Trace class of which to get the stream.
882 @param[in] index Index of the stream to find.
883 @returns Stream at index \p index, or \c NULL
884 on error.
885
886 @prenotnull{trace_class}
887 @pre \p index is lesser than the number of streams contained in
888 the trace class \p trace_class (see
889 bt_trace_get_stream_count()).
890 @postrefcountsame{trace_class}
891 */
892 static inline
893 struct bt_stream *bt_trace_get_stream_by_index(
894 struct bt_trace *trace_class, uint64_t index)
895 {
896 return bt_get(bt_trace_borrow_stream_by_index(trace_class, index));
897 }
898
899 /** @} */
900
901 /**
902 @name Misc. functions
903 @{
904 */
905
906 /**
907 @brief Returns whether or not the CTF IR trace class \p trace_class
908 is static.
909
910 It is guaranteed that a static trace class will never contain new
911 streams, stream classes, or clock classes. A static class is always
912 frozen.
913
914 This function returns #BT_TRUE if bt_trace_set_is_static() was
915 previously called on it.
916
917 @param[in] trace_class Trace class to check.
918 @returns #BT_TRUE if \p trace_class is static,
919
920 @sa bt_trace_set_is_static(): Makes a trace class static.
921 */
922 extern bt_bool bt_trace_is_static(struct bt_trace *trace_class);
923
924 /**
925 @brief Makes the CTF IR trace class \p trace_class static.
926
927 A static trace class is frozen and you cannot call any modifying
928 function on it:
929
930 - bt_trace_add_stream_class()
931 - bt_trace_add_clock_class()
932 - bt_trace_set_environment_field()
933 - bt_trace_set_environment_field_integer()
934 - bt_trace_set_environment_field_string()
935 - bt_trace_add_is_static_listener()
936
937 You cannot create a stream with bt_stream_create() with any of the
938 stream classes of a static trace class.
939
940 @param[in] trace_class Trace class to make static.
941 @returns 0 on success, or a negative value on error.
942
943 @prenotnull{trace_class}
944 @postrefcountsame{trace_class}
945 @postsuccessfrozen{trace_class}
946
947 @sa bt_trace_is_static(): Checks whether or not a given trace class
948 is static.
949 @sa bt_trace_add_is_static_listener(): Adds a listener to a trace
950 class which is called when the trace class is made static.
951 */
952 extern int bt_trace_set_is_static(struct bt_trace *trace_class);
953
954 /**
955 @brief Adds the listener \p listener to the CTF IR trace class
956 \p trace_class which is called when the trace is made static.
957
958 \p listener is called with \p data, the user data, the first time
959 bt_trace_set_is_static() is called on \p trace_class.
960
961 When the trace is destroyed, or when you remove the added listener with
962 bt_trace_remove_is_static_listener(), \p listener_removed is called
963 if it's not \c NULL. You can use \p listener_removed to free any dynamic
964 data which exists only for the added listener. You cannot call
965 any function which modifies \p trace_class during the execution of
966 \p listener_removed, including bt_trace_remove_is_static_listener().
967
968 This function fails if \p trace_class is already static: you need to
969 check the condition first with bt_trace_is_static().
970
971 On success, this function returns a unique numeric identifier for this
972 listener within \p trace. You can use this identifier to remove the
973 specific listener you added with
974 bt_trace_remove_is_static_listener().
975
976 @param[in] trace_class Trace class to which to add the
977 listener.
978 @param[in] listener Listener to add to \p trace_class.
979 @param[in] listener_removed Remove listener called when \p listener
980 is removed from \p trace_class, or
981 \c NULL if you don't need a remove
982 listener.
983 @param[in] data User data passed when \p listener or
984 \p listener_removed is called.
985 @returns A unique numeric identifier for this
986 listener on success (0 or greater), or a
987 negative value on error.
988
989 @prenotnull{trace_class}
990 @prenotnull{listener}
991 @pre \p trace_class is not static.
992 @postrefcountsame{trace_class}
993
994 @sa bt_trace_remove_is_static_listener(): Removes a "trace is
995 static" listener from a trace class previously added with this
996 function.
997 @sa bt_trace_is_static(): Checks whether or not a given trace class
998 is static.
999 @sa bt_trace_set_is_static(): Makes a trace class static.
1000 */
1001 extern int bt_trace_add_is_static_listener(
1002 struct bt_trace *trace_class,
1003 bt_trace_is_static_listener listener,
1004 bt_trace_listener_removed listener_removed, void *data);
1005
1006 /**
1007 @brief Removes the "trace is static" listener identified by
1008 \p listener_id from the trace class \p trace_class.
1009
1010 @param[in] trace_class Trace class from which to remove the listener
1011 identified by \p listener_id.
1012 @param[in] listener_id Identifier of the listener to remove from
1013 \p trace_class.
1014 @returns 0 if this function removed the listener, or
1015 a negative value on error.
1016
1017 @prenotnull{trace_class}
1018 @pre \p listener_id is the identifier of a listener that you previously
1019 added with bt_trace_add_is_static_listener() and did not
1020 already remove with this function.
1021 @postrefcountsame{trace_class}
1022
1023 @sa bt_trace_add_is_static_listener(): Adds a listener to a trace
1024 class which is called when the trace class is made static.
1025 */
1026 extern int bt_trace_remove_is_static_listener(
1027 struct bt_trace *trace_class, int listener_id);
1028
1029 /**
1030 @brief Accepts the visitor \p visitor to visit the hierarchy of the
1031 CTF IR trace class \p trace_class.
1032
1033 This function traverses the hierarchy of \p trace_class in pre-order
1034 and calls \p visitor on each element.
1035
1036 The trace class itself is visited first, then, for each children stream
1037 class, the stream class itself, and all its children event classes.
1038
1039 @param[in] trace_class Trace class to visit.
1040 @param[in] visitor Visiting function.
1041 @param[in] data User data.
1042 @returns 0 on success, or a negative value on error.
1043
1044 @prenotnull{trace_class}
1045 @prenotnull{visitor}
1046 */
1047 extern int bt_trace_visit(struct bt_trace *trace_class,
1048 bt_visitor visitor, void *data);
1049
1050 /** @} */
1051
1052 /** @} */
1053
1054 #ifdef __cplusplus
1055 }
1056 #endif
1057
1058 #endif /* BABELTRACE_CTF_IR_TRACE_H */
This page took 0.05437 seconds and 3 git commands to generate.