1 #ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
2 #define BABELTRACE_CTF_IR_STREAM_CLASS_H
5 * BabelTrace - CTF IR: Stream Class
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
36 #include <babeltrace/ref.h>
39 #include <babeltrace/ctf-ir/visitor.h>
46 @defgroup ctfirstreamclass CTF IR stream class
48 @brief CTF IR stream class.
51 #include <babeltrace/ctf-ir/stream-class.h>
55 See \ref ctfwriterstreamclass which documents additional CTF IR stream
56 class functions exclusive to the CTF writer mode.
58 A CTF IR <strong><em>stream class</em></strong> is a template that you
59 can use to create concrete \link ctfirstream CTF IR streams\endlink.
61 A stream class has the following properties, both of which \em must
62 be unique amongst all the stream classes contained in the same
63 \link ctfirtraceclass CTF IR trace class\endlink:
68 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
69 contains zero or more stream classes,
70 and a stream class contains zero or more
71 \link ctfireventclass event classes\endlink.
72 You can add an event class
73 to a stream class with bt_stream_class_add_event_class().
74 You can add a stream class to a trace class with
75 bt_trace_add_stream_class().
77 A stream class owns three \link ctfirfieldtypes field types\endlink:
79 - An optional <strong>stream packet context</strong> field type, which
80 represents the \c stream.packet.context CTF scope.
81 - An optional <strong>stream event header</strong> field type, which
82 represents the \c stream.event.header CTF scope.
83 - An optional <strong>stream event context</strong> field type, which
84 represents the \c stream.event.context CTF scope.
86 Those three field types \em must be structure field types as of
87 Babeltrace \btversion.
89 As per the CTF specification, the event header field type \em must
90 contain a field named \c id if the stream class contains more than one
93 As a reminder, here's the structure of a CTF packet:
97 Before you can create a stream from a stream class with
98 bt_stream_create(), you \em must add the prepared stream class to a
99 trace class by calling bt_trace_add_stream_class().
101 As with any Babeltrace object, CTF IR stream class objects have
102 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
103 counts</a>. See \ref refs to learn more about the reference counting
104 management of Babeltrace objects.
106 The following functions \em freeze their stream class parameter on
109 - bt_trace_add_stream_class()
111 - bt_writer_create_stream()
112 (\link ctfwriter CTF writer\endlink mode only)
114 You cannot modify a frozen stream class: it is considered immutable,
117 - Adding an event class to it with
118 bt_stream_class_add_event_class(). If the stream class's parent
119 \link ctfirtraceclass trace class\endlink is static, however,
120 you cannot call bt_stream_class_add_event_class()
121 (see bt_trace_is_static() and bt_trace_set_is_static()).
122 - \link refs Reference counting\endlink.
127 @sa ctfwriterstreamclass
130 @brief CTF IR stream class type and functions.
133 @addtogroup ctfirstreamclass
138 @struct bt_stream_class
139 @brief A CTF IR stream class.
142 struct bt_stream_class
;
143 struct bt_event_class
;
145 struct bt_event_header_field
;
146 struct bt_packet_context_field
;
149 @name Creation and parent access functions
154 @brief Creates a default CTF IR stream class named \p name, or a
155 default unnamed stream class if \p name is \c NULL.
157 On success, the packet context field type of the created stream class
158 has the following fields:
160 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
161 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
162 - <code>content_size</code>: a 64-bit unsigned integer field type.
163 - <code>packet_size</code>: a 64-bit unsigned integer field type.
164 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
166 On success, the event header field type of the created stream class
167 has the following fields:
169 - <code>code</code>: a 32-bit unsigned integer field type.
170 - <code>timestamp</code>: a 64-bit unsigned integer field type.
172 You can modify those default field types after the stream class is
173 created with bt_stream_class_set_packet_context_field_type() and
174 bt_stream_class_set_event_header_field_type().
176 @param[in] name Name of the stream class to create (copied on success),
177 or \c NULL to create an unnamed stream class.
178 @returns Created default stream class, or \c NULL on error.
180 @postsuccessrefcountret1
182 @sa bt_stream_class_create_empty(): Creates an empty stream class.
184 extern struct bt_stream_class
*bt_stream_class_create(const char *name
);
186 extern struct bt_trace
*bt_stream_class_borrow_trace(
187 struct bt_stream_class
*stream_class
);
190 @brief Returns the parent CTF IR trace class of the CTF IR stream
191 class \p stream_class.
193 It is possible that the stream class was not added to a trace class
194 yet, in which case this function returns \c NULL. You can add a
195 stream class to a trace class with
196 bt_trace_add_stream_class().
198 @param[in] stream_class Stream class of which to get the parent
200 @returns Parent trace class of \p stream_class,
201 or \c NULL if \p stream_class was not
202 added to a trace class yet or on error.
204 @prenotnull{stream_class}
205 @postrefcountsame{stream_class}
206 @postsuccessrefcountretinc
208 @sa bt_trace_add_stream_class(): Add a stream class to
212 struct bt_trace
*bt_stream_class_get_trace(
213 struct bt_stream_class
*stream_class
)
215 return bt_get(bt_stream_class_borrow_trace(stream_class
));
221 @name Properties functions
226 @brief Returns the name of the CTF IR stream class \p stream_class.
228 On success, \p stream_class remains the sole owner of the returned
231 @param[in] stream_class Stream class of which to get the name.
232 @returns Name of stream class \p stream_class, or
233 \c NULL if \p stream_class is unnamed or
236 @prenotnull{stream_class}
237 @postrefcountsame{stream_class}
239 @sa bt_stream_class_set_name(): Sets the name of a given
242 extern const char *bt_stream_class_get_name(
243 struct bt_stream_class
*stream_class
);
246 @brief Sets the name of the CTF IR stream class
247 \p stream_class to \p name, or resets the name of
250 If \p name is not \c NULL, it must be unique amongst the names of all
251 the stream classes of the trace class to which you eventually add
254 @param[in] stream_class Stream class of which to set the name.
255 @param[in] name Name of the stream class (copied on success), or
256 \c NULL to reset the name of \p stream_class
258 @returns 0 on success, or a negative value on error.
260 @prenotnull{stream_class}
261 @prehot{stream_class}
262 @postrefcountsame{stream_class}
264 @sa bt_stream_class_get_name(): Returns the name of a given
267 extern int bt_stream_class_set_name(
268 struct bt_stream_class
*stream_class
, const char *name
);
271 @brief Returns the numeric ID of the CTF IR stream class \p stream_class.
273 @param[in] stream_class Stream class of which to get the numeric ID.
274 @returns ID of stream class \p stream_class, or a
275 negative value on error.
277 @prenotnull{stream_class}
278 @postrefcountsame{stream_class}
280 @sa bt_stream_class_set_id(): Sets the numeric ID of a given
283 extern int64_t bt_stream_class_get_id(
284 struct bt_stream_class
*stream_class
);
287 @brief Sets the numeric ID of the CTF IR stream class
288 \p stream_class to \p id.
290 \p id must be unique amongst the IDs of all the stream classes
291 of the trace class to which you eventually add \p stream_class.
293 @param[in] stream_class Stream class of which to set the numeric ID.
294 @param[in] id ID of the stream class.
295 @returns 0 on success, or a negative value on error.
297 @prenotnull{stream_class}
298 @prehot{stream_class}
299 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
300 @postrefcountsame{stream_class}
302 @sa bt_stream_class_get_id(): Returns the numeric ID of a given
305 extern int bt_stream_class_set_id(
306 struct bt_stream_class
*stream_class
, uint64_t id
);
311 @name Contained field types functions
315 extern struct bt_field_type
*bt_stream_class_borrow_packet_context_field_type(
316 struct bt_stream_class
*stream_class
);
319 @brief Returns the packet context field type of the CTF IR stream class
322 @param[in] stream_class Stream class of which to get the packet
324 @returns Packet context field type of \p stream_class,
325 or \c NULL if \p stream_class has no packet context
326 field type or on error.
328 @prenotnull{stream_class}
329 @postrefcountsame{stream_class}
330 @post <strong>On success, if the return value is a field type</strong>, its
331 reference count is incremented.
333 @sa bt_stream_class_set_packet_context_field_type(): Sets the packet
334 context field type of a given stream class.
337 struct bt_field_type
*bt_stream_class_get_packet_context_field_type(
338 struct bt_stream_class
*stream_class
)
340 return bt_get(bt_stream_class_borrow_packet_context_field_type(
345 struct bt_packet_context_field
*bt_stream_class_create_packet_context_field(
346 struct bt_stream_class
*stream_class
);
349 @brief Sets the packet context field type of the CTF IR stream class
350 \p stream_class to \p packet_context_type, or unsets the current packet
351 context field type from \p stream_class.
353 If \p packet_context_type is \c NULL, then this function unsets the current
354 packet context field type from \p stream_class, effectively making
355 \p stream_class a stream class without a packet context field type.
357 As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
358 \p packet_context_type \em must be a CTF IR structure field type object.
360 @param[in] stream_class Stream class of which to set the packet
362 @param[in] packet_context_type Packet context field type, or \c NULL to unset
363 the current packet context field type.
364 @returns 0 on success, or a negative value on error.
366 @prenotnull{stream_class}
367 @prehot{stream_class}
368 @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
369 structure field type.
370 @postrefcountsame{stream_class}
371 @post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
372 the reference count of \p packet_context_type is incremented.
374 @sa bt_stream_class_get_packet_context_field_type(): Returns the packet
375 context field type of a given stream class.
377 extern int bt_stream_class_set_packet_context_field_type(
378 struct bt_stream_class
*stream_class
,
379 struct bt_field_type
*packet_context_type
);
381 extern struct bt_field_type
*
382 bt_stream_class_borrow_event_header_field_type(
383 struct bt_stream_class
*stream_class
);
386 @brief Returns the event header field type of the CTF IR stream class
389 @param[in] stream_class Stream class of which to get the event header
391 @returns Event header field type of \p stream_class,
392 or \c NULL if \p stream_class has no event header field
395 @prenotnull{stream_class}
396 @postrefcountsame{stream_class}
397 @post <strong>On success, if the return value is a field type</strong>, its
398 reference count is incremented.
400 @sa bt_stream_class_set_event_header_field_type(): Sets the event
401 header field type of a given stream class.
404 struct bt_field_type
*bt_stream_class_get_event_header_field_type(
405 struct bt_stream_class
*stream_class
)
407 return bt_get(bt_stream_class_borrow_event_header_field_type(
412 @brief Sets the event header field type of the CTF IR stream class
413 \p stream_class to \p event_header_type, or unsets the current event
414 header field type from \p stream_class.
416 If \p event_header_type is \c NULL, then this function unsets the current
417 event header field type from \p stream_class, effectively making \p stream_class
418 a stream class without a event header field type.
420 As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
421 \p event_header_type \em must be a CTF IR structure field type object.
423 @param[in] stream_class Stream class of which to set the event
425 @param[in] event_header_type Event header field type, or \c NULL to unset
426 the current event header field type.
427 @returns 0 on success, or a negative value on error.
429 @prenotnull{stream_class}
430 @prehot{stream_class}
431 @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
432 structure field type.
433 @postrefcountsame{stream_class}
434 @post <strong>On success, if \p event_header_type is not \c NULL</strong>,
435 the reference count of \p event_header_type is incremented.
437 @sa bt_stream_class_get_event_header_field_type(): Returns the event
438 header field type of a given stream class.
440 extern int bt_stream_class_set_event_header_field_type(
441 struct bt_stream_class
*stream_class
,
442 struct bt_field_type
*event_header_type
);
444 extern struct bt_event_header_field
*bt_stream_class_create_event_header_field(
445 struct bt_stream_class
*stream_class
);
447 extern struct bt_field_type
*
448 bt_stream_class_borrow_event_context_field_type(
449 struct bt_stream_class
*stream_class
);
452 @brief Returns the event context field type of the CTF IR stream class
455 @param[in] stream_class Stream class of which to get the event context
457 @returns Event context field type of \p stream_class,
458 or \c NULL if \p stream_class has no event context field
461 @prenotnull{stream_class}
462 @postrefcountsame{stream_class}
463 @post <strong>On success, if the return value is a field type</strong>,
464 its reference count is incremented.
467 @sa bt_stream_class_set_event_context_field_type(): Sets the event
468 context field type of a given stream class.
471 struct bt_field_type
*
472 bt_stream_class_get_event_context_field_type(
473 struct bt_stream_class
*stream_class
)
475 return bt_get(bt_stream_class_borrow_event_context_field_type(
480 @brief Sets the event context field type of the CTF IR stream class
481 \p stream_class to \p event_context_type, or unsets the current event
482 context field type from \p stream_class.
484 If \p event_context_type is \c NULL, then this function unsets the current
485 event context field type from \p stream_class, effectively making \p
486 stream_class a stream class without a event context field type.
488 As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
489 \p event_context_type \em must be a CTF IR structure field type object.
491 @param[in] stream_class Stream class of which to set the packet
493 @param[in] event_context_type Event context field type, or \c NULL to unset
494 the current event context field type.
495 @returns 0 on success, or a negative value on error.
497 @prenotnull{stream_class}
498 @prehot{stream_class}
499 @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
500 structure field type.
501 @postrefcountsame{stream_class}
502 @post <strong>On success, if \p event_context_type is not \c NULL</strong>,
503 the reference count of \p event_context_type is incremented.
505 @sa bt_stream_class_get_event_context_field_type(): Returns the event context
506 field type of a given stream class.
508 extern int bt_stream_class_set_event_context_field_type(
509 struct bt_stream_class
*stream_class
,
510 struct bt_field_type
*event_context_type
);
515 @name Event class children functions
520 @brief Returns the number of event classes contained in the
521 CTF IR stream class \p stream_class.
523 @param[in] stream_class Stream class of which to get the number
524 of children event classes.
525 @returns Number of children event classes
526 contained in \p stream_class, or
527 a negative value on error.
529 @prenotnull{stream_class}
530 @postrefcountsame{stream_class}
532 extern int64_t bt_stream_class_get_event_class_count(
533 struct bt_stream_class
*stream_class
);
535 extern struct bt_event_class
*bt_stream_class_borrow_event_class_by_index(
536 struct bt_stream_class
*stream_class
, uint64_t index
);
539 @brief Returns the event class at index \p index in the CTF IR stream
540 class \p stream_class.
542 @param[in] stream_class Stream class of which to get the event class.
543 @param[in] index Index of the event class to find.
544 @returns Event class at index \p index, or \c NULL
547 @prenotnull{stream_class}
548 @pre \p index is lesser than the number of event classes contained in the
549 stream class \p stream_class (see
550 bt_stream_class_get_event_class_count()).
551 @postrefcountsame{stream_class}
552 @postsuccessrefcountretinc
554 @sa bt_stream_class_get_event_class_by_id(): Finds an event class
558 struct bt_event_class
*bt_stream_class_get_event_class_by_index(
559 struct bt_stream_class
*stream_class
, uint64_t index
)
561 return bt_get(bt_stream_class_borrow_event_class_by_index(stream_class
,
565 extern struct bt_event_class
*bt_stream_class_borrow_event_class_by_id(
566 struct bt_stream_class
*stream_class
, uint64_t id
);
569 @brief Returns the event class with ID \c id found in the CTF IR stream
570 class \p stream_class.
572 @param[in] stream_class Stream class of which to get the event class.
573 @param[in] id ID of the event class to find.
574 @returns Event class with ID \p id, or \c NULL
577 @prenotnull{stream_class}
578 @postrefcountsame{stream_class}
579 @postsuccessrefcountretinc
582 struct bt_event_class
*bt_stream_class_get_event_class_by_id(
583 struct bt_stream_class
*stream_class
, uint64_t id
)
585 return bt_get(bt_stream_class_borrow_event_class_by_id(stream_class
,
590 @brief Adds the CTF IR event class \p event_class to the
591 CTF IR stream class \p stream_class.
593 On success, \p event_class becomes the child of \p stream_class.
595 You can only add a given event class to one stream class.
597 You can call this function even if \p stream_class is frozen. Adding
598 event classes is the only operation that is permitted
599 on a frozen stream class.
601 This function tries to resolve the needed
602 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
603 types that are found anywhere in the context or payload field
604 types of \p event_class. If any automatic resolving fails:
606 - If the needed field type should be found in one of the root field
607 types of \p event_class or \p stream_class, this function fails.
608 - If \p stream_class is the child of a
609 \link ctfirtraceclass CTF IR trace class\endlink (it was added
610 with bt_trace_add_stream_class()), this function fails.
611 - If \p stream_class is not the child of a trace class yet, the
612 automatic resolving is reported to the next call to
613 bt_trace_add_stream_class() with \p stream_class.
615 @param[in] stream_class Stream class to which to add \p event_class.
616 @param[in] event_class Event class to add to \p stream_class.
617 @returns 0 on success, or a negative value on error.
619 @prenotnull{stream_class}
620 @prenotnull{event_class}
622 @postrefcountsame{stream_class}
623 @postsuccessrefcountinc{event_class}
624 @postsuccessfrozen{event_class}
626 extern int bt_stream_class_add_event_class(
627 struct bt_stream_class
*stream_class
,
628 struct bt_event_class
*event_class
);
638 @brief Accepts the visitor \p visitor to visit the hierarchy of the
639 CTF IR stream class \p stream_class.
641 This function traverses the hierarchy of \p stream_class in pre-order
642 and calls \p visitor on each element.
644 The stream class itself is visited first, and then all its children
647 @param[in] stream_class Stream class to visit.
648 @param[in] visitor Visiting function.
649 @param[in] data User data.
650 @returns 0 on success, or a negative value on error.
652 @prenotnull{stream_class}
655 extern int bt_stream_class_visit(struct bt_stream_class
*stream_class
,
656 bt_visitor visitor
, void *data
);
666 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */
This page took 0.068513 seconds and 4 git commands to generate.