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
34 #include <babeltrace/ctf-ir/visitor.h>
41 @defgroup ctfirstreamclass CTF IR stream class
43 @brief CTF IR stream class.
46 #include <babeltrace/ctf-ir/stream-class.h>
50 See \ref ctfwriterstreamclass which documents additional CTF IR stream
51 class functions exclusive to the CTF writer mode.
53 A CTF IR <strong><em>stream class</em></strong> is a template that you
54 can use to create concrete \link ctfirstream CTF IR streams\endlink.
56 A stream class has the following properties, both of which \em must
57 be unique amongst all the stream classes contained in the same
58 \link ctfirtraceclass CTF IR trace class\endlink:
63 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
64 contains zero or more stream classes,
65 and a stream class contains zero or more
66 \link ctfireventclass event classes\endlink.
67 You can add an event class
68 to a stream class with bt_ctf_stream_class_add_event_class().
69 You can add a stream class to a trace class with
70 bt_ctf_trace_add_stream_class().
72 A stream class owns three \link ctfirfieldtypes field types\endlink:
74 - An optional <strong>stream packet context</strong> field type, which
75 represents the \c stream.packet.context CTF scope.
76 - An optional <strong>stream event header</strong> field type, which
77 represents the \c stream.event.header CTF scope.
78 - An optional <strong>stream event context</strong> field type, which
79 represents the \c stream.event.context CTF scope.
81 Those three field types \em must be structure field types as of
82 Babeltrace \btversion.
84 As per the CTF specification, the event header field type \em must
85 contain a field named \c id if the stream class contains more than one
88 As a reminder, here's the structure of a CTF packet:
92 Before you can create a stream from a stream class with
93 bt_ctf_stream_create(), you \em must add the prepared stream class to a
94 trace class by calling bt_ctf_trace_add_stream_class().
96 As with any Babeltrace object, CTF IR stream class objects have
97 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
98 counts</a>. See \ref refs to learn more about the reference counting
99 management of Babeltrace objects.
101 The following functions \em freeze their stream class parameter on
104 - bt_ctf_trace_add_stream_class()
105 - bt_ctf_event_create()
106 - bt_ctf_writer_create_stream()
107 (\link ctfwriter CTF writer\endlink mode only)
109 You cannot modify a frozen stream class: it is considered immutable,
112 - Adding an event class to it with
113 bt_ctf_stream_class_add_event_class(). If the stream class's parent
114 \link ctfirtraceclass trace class\endlink is static, however,
115 you cannot call bt_ctf_stream_class_add_event_class()
116 (see bt_ctf_trace_is_static() and bt_ctf_trace_set_is_static()).
117 - \link refs Reference counting\endlink.
122 @sa ctfwriterstreamclass
125 @brief CTF IR stream class type and functions.
128 @addtogroup ctfirstreamclass
133 @struct bt_ctf_stream_class
134 @brief A CTF IR stream class.
137 struct bt_ctf_stream_class
;
138 struct bt_ctf_event_class
;
142 @name Creation and parent access functions
147 @brief Creates an empty CTF IR stream class named \p name, or an
148 unnamed empty stream class if \p name is \c NULL.
150 On success, the packet context, event header, and event context field
151 types are empty structure field types. You can modify those default
152 field types after the stream class is created with
153 bt_ctf_stream_class_set_packet_context_type(),
154 bt_ctf_stream_class_set_event_header_type(), and
155 bt_ctf_stream_class_set_event_context_type().
157 @param[in] name Name of the stream class to create (copied on success),
158 or \c NULL to create an unnamed stream class.
159 @returns Created empty stream class, or \c NULL on error.
161 @postsuccessrefcountret1
163 @sa bt_ctf_stream_class_create(): Creates a default stream class.
165 extern struct bt_ctf_stream_class
*bt_ctf_stream_class_create_empty(
169 @brief Creates a default CTF IR stream class named \p name, or a
170 default unnamed stream class if \p name is \c NULL.
172 On success, the packet context field type of the created stream class
173 has the following fields:
175 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
176 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
177 - <code>content_size</code>: a 64-bit unsigned integer field type.
178 - <code>packet_size</code>: a 64-bit unsigned integer field type.
179 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
181 On success, the event header field type of the created stream class
182 has the following fields:
184 - <code>code</code>: a 32-bit unsigned integer field type.
185 - <code>timestamp</code>: a 64-bit unsigned integer field type.
187 You can modify those default field types after the stream class is
188 created with bt_ctf_stream_class_set_packet_context_type() and
189 bt_ctf_stream_class_set_event_header_type().
191 @param[in] name Name of the stream class to create (copied on success),
192 or \c NULL to create an unnamed stream class.
193 @returns Created default stream class, or \c NULL on error.
195 @postsuccessrefcountret1
197 @sa bt_ctf_stream_class_create_empty(): Creates an empty stream class.
199 extern struct bt_ctf_stream_class
*bt_ctf_stream_class_create(const char *name
);
202 @brief Returns the parent CTF IR trace class of the CTF IR stream
203 class \p stream_class.
205 It is possible that the stream class was not added to a trace class
206 yet, in which case this function returns \c NULL. You can add a
207 stream class to a trace class with
208 bt_ctf_trace_add_stream_class().
210 @param[in] stream_class Stream class of which to get the parent
212 @returns Parent trace class of \p stream_class,
213 or \c NULL if \p stream_class was not
214 added to a trace class yet or on error.
216 @prenotnull{stream_class}
217 @postrefcountsame{stream_class}
218 @postsuccessrefcountretinc
220 @sa bt_ctf_trace_add_stream_class(): Add a stream class to
223 extern struct bt_ctf_trace
*bt_ctf_stream_class_get_trace(
224 struct bt_ctf_stream_class
*stream_class
);
229 @name Properties functions
234 @brief Returns the name of the CTF IR stream class \p stream_class.
236 On success, \p stream_class remains the sole owner of the returned
239 @param[in] stream_class Stream class of which to get the name.
240 @returns Name of stream class \p stream_class, or
241 \c NULL if \p stream_class is unnamed or
244 @prenotnull{stream_class}
245 @postrefcountsame{stream_class}
247 @sa bt_ctf_stream_class_set_name(): Sets the name of a given
250 extern const char *bt_ctf_stream_class_get_name(
251 struct bt_ctf_stream_class
*stream_class
);
254 @brief Sets the name of the CTF IR stream class
255 \p stream_class to \p name, or resets the name of
258 If \p name is not \c NULL, it must be unique amongst the names of all
259 the stream classes of the trace class to which you eventually add
262 @param[in] stream_class Stream class of which to set the name.
263 @param[in] name Name of the stream class (copied on success), or
264 \c NULL to reset the name of \p stream_class
266 @returns 0 on success, or a negative value on error.
268 @prenotnull{stream_class}
269 @prehot{stream_class}
270 @postrefcountsame{stream_class}
272 @sa bt_ctf_stream_class_get_name(): Returns the name of a given
275 extern int bt_ctf_stream_class_set_name(
276 struct bt_ctf_stream_class
*stream_class
, const char *name
);
279 @brief Returns the numeric ID of the CTF IR stream class \p stream_class.
281 @param[in] stream_class Stream class of which to get the numeric ID.
282 @returns ID of stream class \p stream_class, or a
283 negative value on error.
285 @prenotnull{stream_class}
286 @postrefcountsame{stream_class}
288 @sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
291 extern int64_t bt_ctf_stream_class_get_id(
292 struct bt_ctf_stream_class
*stream_class
);
295 @brief Sets the numeric ID of the CTF IR stream class
296 \p stream_class to \p id.
298 \p id must be unique amongst the IDs of all the stream classes
299 of the trace class to which you eventually add \p stream_class.
301 @param[in] stream_class Stream class of which to set the numeric ID.
302 @param[in] id ID of the stream class.
303 @returns 0 on success, or a negative value on error.
305 @prenotnull{stream_class}
306 @prehot{stream_class}
307 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
308 @postrefcountsame{stream_class}
310 @sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
313 extern int bt_ctf_stream_class_set_id(
314 struct bt_ctf_stream_class
*stream_class
, uint64_t id
);
319 @name Contained field types functions
324 @brief Returns the packet context field type of the CTF IR stream class
327 @param[in] stream_class Stream class of which to get the packet
329 @returns Packet context field type of \p stream_class,
330 or \c NULL if \p stream_class has no packet context
331 field type or on error.
333 @prenotnull{stream_class}
334 @postrefcountsame{stream_class}
335 @post <strong>On success, if the return value is a field type</strong>, its
336 reference count is incremented.
338 @sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
339 context field type of a given stream class.
341 extern struct bt_ctf_field_type
*bt_ctf_stream_class_get_packet_context_type(
342 struct bt_ctf_stream_class
*stream_class
);
345 @brief Sets the packet context field type of the CTF IR stream class
346 \p stream_class to \p packet_context_type, or unsets the current packet
347 context field type from \p stream_class.
349 If \p packet_context_type is \c NULL, then this function unsets the current
350 packet context field type from \p stream_class, effectively making
351 \p stream_class a stream class without a packet context field type.
353 As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
354 \p packet_context_type \em must be a CTF IR structure field type object.
356 @param[in] stream_class Stream class of which to set the packet
358 @param[in] packet_context_type Packet context field type, or \c NULL to unset
359 the current packet context field type.
360 @returns 0 on success, or a negative value on error.
362 @prenotnull{stream_class}
363 @prehot{stream_class}
364 @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
365 structure field type.
366 @postrefcountsame{stream_class}
367 @post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
368 the reference count of \p packet_context_type is incremented.
370 @sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
371 context field type of a given stream class.
373 extern int bt_ctf_stream_class_set_packet_context_type(
374 struct bt_ctf_stream_class
*stream_class
,
375 struct bt_ctf_field_type
*packet_context_type
);
378 @brief Returns the event header field type of the CTF IR stream class
381 @param[in] stream_class Stream class of which to get the event header
383 @returns Event header field type of \p stream_class,
384 or \c NULL if \p stream_class has no event header field
387 @prenotnull{stream_class}
388 @postrefcountsame{stream_class}
389 @post <strong>On success, if the return value is a field type</strong>, its
390 reference count is incremented.
392 @sa bt_ctf_stream_class_set_event_header_type(): Sets the event
393 header field type of a given stream class.
395 extern struct bt_ctf_field_type
*
396 bt_ctf_stream_class_get_event_header_type(
397 struct bt_ctf_stream_class
*stream_class
);
400 @brief Sets the event header field type of the CTF IR stream class
401 \p stream_class to \p event_header_type, or unsets the current event
402 header field type from \p stream_class.
404 If \p event_header_type is \c NULL, then this function unsets the current
405 event header field type from \p stream_class, effectively making \p stream_class
406 a stream class without a event header field type.
408 As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
409 \p event_header_type \em must be a CTF IR structure field type object.
411 @param[in] stream_class Stream class of which to set the event
413 @param[in] event_header_type Event header field type, or \c NULL to unset
414 the current event header field type.
415 @returns 0 on success, or a negative value on error.
417 @prenotnull{stream_class}
418 @prehot{stream_class}
419 @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
420 structure field type.
421 @postrefcountsame{stream_class}
422 @post <strong>On success, if \p event_header_type is not \c NULL</strong>,
423 the reference count of \p event_header_type is incremented.
425 @sa bt_ctf_stream_class_get_event_header_type(): Returns the event
426 header field type of a given stream class.
428 extern int bt_ctf_stream_class_set_event_header_type(
429 struct bt_ctf_stream_class
*stream_class
,
430 struct bt_ctf_field_type
*event_header_type
);
433 @brief Returns the event context field type of the CTF IR stream class
436 @param[in] stream_class Stream class of which to get the event context
438 @returns Event context field type of \p stream_class,
439 or \c NULL if \p stream_class has no event context field
442 @prenotnull{stream_class}
443 @postrefcountsame{stream_class}
444 @post <strong>On success, if the return value is a field type</strong>,
445 its reference count is incremented.
448 @sa bt_ctf_stream_class_set_event_context_type(): Sets the event
449 context field type of a given stream class.
451 extern struct bt_ctf_field_type
*
452 bt_ctf_stream_class_get_event_context_type(
453 struct bt_ctf_stream_class
*stream_class
);
456 @brief Sets the event context field type of the CTF IR stream class
457 \p stream_class to \p event_context_type, or unsets the current event
458 context field type from \p stream_class.
460 If \p event_context_type is \c NULL, then this function unsets the current
461 event context field type from \p stream_class, effectively making \p
462 stream_class a stream class without a event context field type.
464 As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
465 \p event_context_type \em must be a CTF IR structure field type object.
467 @param[in] stream_class Stream class of which to set the packet
469 @param[in] event_context_type Event context field type, or \c NULL to unset
470 the current event context field type.
471 @returns 0 on success, or a negative value on error.
473 @prenotnull{stream_class}
474 @prehot{stream_class}
475 @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
476 structure field type.
477 @postrefcountsame{stream_class}
478 @post <strong>On success, if \p event_context_type is not \c NULL</strong>,
479 the reference count of \p event_context_type is incremented.
481 @sa bt_ctf_stream_class_get_event_context_type(): Returns the event context
482 field type of a given stream class.
484 extern int bt_ctf_stream_class_set_event_context_type(
485 struct bt_ctf_stream_class
*stream_class
,
486 struct bt_ctf_field_type
*event_context_type
);
491 @name Event class children functions
496 @brief Returns the number of event classes contained in the
497 CTF IR stream class \p stream_class.
499 @param[in] stream_class Stream class of which to get the number
500 of children event classes.
501 @returns Number of children event classes
502 contained in \p stream_class, or
503 a negative value on error.
505 @prenotnull{stream_class}
506 @postrefcountsame{stream_class}
508 extern int64_t bt_ctf_stream_class_get_event_class_count(
509 struct bt_ctf_stream_class
*stream_class
);
512 @brief Returns the event class at index \p index in the CTF IR stream
513 class \p stream_class.
515 @param[in] stream_class Stream class of which to get the event class.
516 @param[in] index Index of the event class to find.
517 @returns Event class at index \p index, or \c NULL
520 @prenotnull{stream_class}
521 @pre \p index is lesser than the number of event classes contained in the
522 stream class \p stream_class (see
523 bt_ctf_stream_class_get_event_class_count()).
524 @postrefcountsame{stream_class}
525 @postsuccessrefcountretinc
527 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
530 extern struct bt_ctf_event_class
*bt_ctf_stream_class_get_event_class_by_index(
531 struct bt_ctf_stream_class
*stream_class
, uint64_t index
);
534 @brief Returns the event class with ID \c id found in the CTF IR stream
535 class \p stream_class.
537 @param[in] stream_class Stream class of which to get the event class.
538 @param[in] id ID of the event class to find.
539 @returns Event class with ID \p id, or \c NULL
542 @prenotnull{stream_class}
543 @postrefcountsame{stream_class}
544 @postsuccessrefcountretinc
546 extern struct bt_ctf_event_class
*bt_ctf_stream_class_get_event_class_by_id(
547 struct bt_ctf_stream_class
*stream_class
, uint64_t id
);
550 @brief Adds the CTF IR event class \p event_class to the
551 CTF IR stream class \p stream_class.
553 On success, \p event_class becomes the child of \p stream_class.
555 You can only add a given event class to one stream class.
557 You can call this function even if \p stream_class is frozen. Adding
558 event classes is the only operation that is permitted
559 on a frozen stream class.
561 This function tries to resolve the needed
562 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
563 types that are found anywhere in the context or payload field
564 types of \p event_class. If any automatic resolving fails:
566 - If the needed field type should be found in one of the root field
567 types of \p event_class or \p stream_class, this function fails.
568 - If \p stream_class is the child of a
569 \link ctfirtraceclass CTF IR trace class\endlink (it was added
570 with bt_ctf_trace_add_stream_class()), this function fails.
571 - If \p stream_class is not the child of a trace class yet, the
572 automatic resolving is reported to the next call to
573 bt_ctf_trace_add_stream_class() with \p stream_class.
575 @param[in] stream_class Stream class to which to add \p event_class.
576 @param[in] event_class Event class to add to \p stream_class.
577 @returns 0 on success, or a negative value on error.
579 @prenotnull{stream_class}
580 @prenotnull{event_class}
582 @postrefcountsame{stream_class}
583 @postsuccessrefcountinc{event_class}
584 @postsuccessfrozen{event_class}
586 extern int bt_ctf_stream_class_add_event_class(
587 struct bt_ctf_stream_class
*stream_class
,
588 struct bt_ctf_event_class
*event_class
);
598 @brief Accepts the visitor \p visitor to visit the hierarchy of the
599 CTF IR stream class \p stream_class.
601 This function traverses the hierarchy of \p stream_class in pre-order
602 and calls \p visitor on each element.
604 The stream class itself is visited first, and then all its children
607 @param[in] stream_class Stream class to visit.
608 @param[in] visitor Visiting function.
609 @param[in] data User data.
610 @returns 0 on success, or a negative value on error.
612 @prenotnull{stream_class}
615 extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class
*stream_class
,
616 bt_ctf_visitor visitor
, void *data
);
626 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */
This page took 0.049342 seconds and 4 git commands to generate.