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 See \ref ctfirwriterstreamclass which documents additional CTF IR stream
47 class functions exclusive to the CTF IR writer mode.
49 A CTF IR <strong><em>stream class</em></strong> is a template that you
50 can use to create concrete \link ctfirstream CTF IR streams\endlink.
52 A stream class has the following properties, both of which \em must
53 be unique amongst all the stream classes contained in the same
54 \link ctfirtraceclass CTF IR trace class\endlink:
59 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
60 contains zero or more stream classes,
61 and a stream class contains zero or more
62 \link ctfireventclass event classes\endlink.
63 You can add an event class
64 to a stream class with bt_ctf_stream_class_add_event_class().
65 You can add a stream class to a trace class with
66 bt_ctf_trace_add_stream_class().
68 A stream class owns three \link ctfirfieldtypes field types\endlink:
70 - An optional <strong>stream packet context</strong> field type, which
71 represents the \c stream.packet.context CTF scope.
72 - An optional <strong>stream event header</strong> field type, which
73 represents the \c stream.event.header CTF scope.
74 - An optional <strong>stream event context</strong> field type, which
75 represents the \c stream.event.context CTF scope.
77 Those three field types \em must be structure field types as of
78 Babeltrace \btversion.
80 As per the CTF specification, the event header field type \em must
81 contain a field named \c id if the stream class contains more than one
84 As a reminder, here's the structure of a CTF packet:
88 Before you can create a stream from a stream class with
89 bt_ctf_stream_create(), you \em must add the prepared stream class to a
90 trace class by calling bt_ctf_trace_add_stream_class().
92 As with any Babeltrace object, CTF IR stream class objects have
93 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
94 counts</a>. See \ref refs to learn more about the reference counting
95 management of Babeltrace objects.
97 The following functions \em freeze their stream class parameter on
100 - bt_ctf_trace_add_stream_class()
101 - bt_ctf_event_create()
102 - bt_ctf_writer_create_stream()
103 (\link ctfirwriter CTF IR writer\endlink mode only)
105 You cannot modify a frozen stream class: it is considered immutable,
108 - Adding an event class to it with
109 bt_ctf_stream_class_add_event_class().
110 - \link refs Reference counting\endlink.
115 @sa ctfirwriterstreamclass
118 @brief CTF IR stream class type and functions.
121 @addtogroup ctfirstreamclass
126 @struct bt_ctf_stream_class
127 @brief A CTF IR stream class.
130 struct bt_ctf_stream_class
;
131 struct bt_ctf_event_class
;
135 @name Creation and parent access functions
140 @brief Creates a default CTF IR stream class named \p name, or a
141 default unnamed stream class if \p name is \c NULL.
143 On success, the packet context field type of the created stream class
144 has the following fields:
146 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
147 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
148 - <code>content_size</code>: a 64-bit unsigned integer field type.
149 - <code>packet_size</code>: a 64-bit unsigned integer field type.
150 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
152 On success, the event header field type of the created stream class
153 has the following fields:
155 - <code>code</code>: a 32-bit unsigned integer field type.
156 - <code>timestamp</code>: a 64-bit unsigned integer field type.
158 You can modify those default field types after the stream class is
159 created with bt_ctf_stream_class_set_packet_context_type() and
160 bt_ctf_stream_class_set_event_header_type().
162 @param[in] name Name of the stream class to create (can be \c NULL to
163 create an unnamed stream class).
164 @returns Created stream class, or \c NULL on error.
166 @postsuccessrefcountret1
168 extern struct bt_ctf_stream_class
*bt_ctf_stream_class_create(const char *name
);
171 @brief Returns the parent CTF IR trace class of the CTF IR stream
172 class \p stream_class.
174 It is possible that the stream class was not added to a trace class
175 yet, in which case this function returns \c NULL. You can add a
176 stream class to a trace class with
177 bt_ctf_trace_add_stream_class().
179 @param[in] stream_class Stream class of which to get the parent
181 @returns Parent trace class of \p stream_class,
182 or \c NULL if \p stream_class was not
183 added to a trace class yet or on error.
185 @prenotnull{stream_class}
186 @postsuccessrefcountretinc
188 @sa bt_ctf_trace_add_stream_class(): Add a stream class to
191 extern struct bt_ctf_trace
*bt_ctf_stream_class_get_trace(
192 struct bt_ctf_stream_class
*stream_class
);
197 @name Properties functions
202 @brief Returns the name of the CTF IR stream class \p stream_class.
204 On success, \p stream_class remains the sole owner of the returned
207 @param[in] stream_class Stream class of which to get the name.
208 @returns Name of stream class \p stream_class, or
209 \c NULL if \p stream_class is unnamed or
212 @prenotnull{stream_class}
213 @postrefcountsame{stream_class}
215 @sa bt_ctf_stream_class_set_name(): Sets the name of a given
218 extern const char *bt_ctf_stream_class_get_name(
219 struct bt_ctf_stream_class
*stream_class
);
222 @brief Sets the name of the CTF IR stream class
223 \p stream_class to \p name.
225 \p name must be unique amongst the names of all the stream classes
226 of the trace class to which you eventually add \p stream_class.
228 @param[in] stream_class Stream class of which to set the name.
229 @param[in] name Name of the stream class (copied on success).
230 @returns 0 on success, or a negative value on error.
232 @prenotnull{stream_class}
234 @prehot{stream_class}
235 @postrefcountsame{stream_class}
237 @sa bt_ctf_stream_class_get_name(): Returns the name of a given
240 extern int bt_ctf_stream_class_set_name(
241 struct bt_ctf_stream_class
*stream_class
, const char *name
);
244 @brief Returns the numeric ID of the CTF IR stream class \p stream_class.
246 @param[in] stream_class Stream class of which to get the numeric ID.
247 @returns ID of stream class \p stream_class, or a
248 negative value on error.
250 @prenotnull{stream_class}
251 @postrefcountsame{stream_class}
253 @sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
256 extern int64_t bt_ctf_stream_class_get_id(
257 struct bt_ctf_stream_class
*stream_class
);
260 @brief Sets the numeric ID of the CTF IR stream class
261 \p stream_class to \p id.
263 \p id must be unique amongst the IDs of all the stream classes
264 of the trace class to which you eventually add \p stream_class.
266 @param[in] stream_class Stream class of which to set the numeric ID.
267 @param[in] id ID of the stream class.
268 @returns 0 on success, or a negative value on error.
270 @prenotnull{stream_class}
271 @prehot{stream_class}
272 @postrefcountsame{stream_class}
274 @sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
277 extern int bt_ctf_stream_class_set_id(
278 struct bt_ctf_stream_class
*stream_class
, uint32_t id
);
283 @name Contained field types functions
288 @brief Returns the packet context field type of the CTF IR stream class
291 @param[in] stream_class Stream class of which to get the packet
293 @returns Packet context field type of \p stream_class,
296 @prenotnull{stream_class}
297 @postsuccessrefcountretinc
299 @sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
300 context field type of a given stream class.
302 extern struct bt_ctf_field_type
*bt_ctf_stream_class_get_packet_context_type(
303 struct bt_ctf_stream_class
*stream_class
);
306 @brief Sets the packet context field type of the CTF IR stream class
307 \p stream_class to \p packet_context_type.
309 As of Babeltrace \btversion, \p packet_context_type \em must be a
310 CTF IR structure field type object.
312 @param[in] stream_class Stream class of which to set the packet
314 @param[in] packet_context_type Packet context field type.
315 @returns 0 on success, or a negative value on error.
317 @prenotnull{stream_class}
318 @prenotnull{packet_context_type}
319 @prehot{stream_class}
320 @preisstructft{packet_context_type}
321 @postrefcountsame{stream_class}
322 @postsuccessrefcountinc{packet_context_type}
324 @sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
325 context field type of a given stream class.
327 extern int bt_ctf_stream_class_set_packet_context_type(
328 struct bt_ctf_stream_class
*stream_class
,
329 struct bt_ctf_field_type
*packet_context_type
);
332 @brief Returns the event header field type of the CTF IR stream class
335 @param[in] stream_class Stream class of which to get the event header
337 @returns Event header field type of \p stream_class,
340 @prenotnull{stream_class}
341 @postsuccessrefcountretinc
343 @sa bt_ctf_stream_class_set_event_header_type(): Sets the event
344 header field type of a given stream class.
346 extern struct bt_ctf_field_type
*
347 bt_ctf_stream_class_get_event_header_type(
348 struct bt_ctf_stream_class
*stream_class
);
351 @brief Sets the event header field type of the CTF IR stream class
352 \p stream_class to \p event_header_type.
354 As of Babeltrace \btversion, \p event_header_type \em must be a
355 CTF IR structure field type object.
357 @param[in] stream_class Stream class of which to set the event
359 @param[in] event_header_type Event header field type.
360 @returns 0 on success, or a negative value on error.
362 @prenotnull{stream_class}
363 @prenotnull{event_header_type}
364 @prehot{stream_class}
365 @preisstructft{event_header_type}
366 @postrefcountsame{stream_class}
367 @postsuccessrefcountinc{event_header_type}
369 @sa bt_ctf_stream_class_get_event_header_type(): Returns the event
370 header field type of a given stream class.
372 extern int bt_ctf_stream_class_set_event_header_type(
373 struct bt_ctf_stream_class
*stream_class
,
374 struct bt_ctf_field_type
*event_header_type
);
377 @brief Returns the per-stream class event context field type of the
378 CTF IR stream class \p stream_class.
380 @param[in] stream_class Stream class of which to get the per-stream
381 class event context field type.
382 @returns Per-stream class event context field type of
383 \p stream_class, or \c NULL on error.
385 @prenotnull{stream_class}
386 @postsuccessrefcountretinc
388 @sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
389 class event context field type of a given stream class.
391 extern struct bt_ctf_field_type
*
392 bt_ctf_stream_class_get_event_context_type(
393 struct bt_ctf_stream_class
*stream_class
);
396 @brief Sets the per-stream class event context field type of the CTF
397 IR stream class \p stream_class to \p event_context_type.
399 As of Babeltrace \btversion, \p event_context_type \em must be a
400 CTF IR structure field type object.
402 @param[in] stream_class Stream class of which to set the
403 per-stream class event context
405 @param[in] event_context_type Per-stream class event context context
407 @returns 0 on success, or a negative value on error.
409 @prenotnull{stream_class}
410 @prenotnull{event_context_type}
411 @prehot{stream_class}
412 @preisstructft{event_context_type}
413 @postrefcountsame{stream_class}
414 @postsuccessrefcountinc{event_context_type}
416 @sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
417 class event context field type of a given stream class.
419 extern int bt_ctf_stream_class_set_event_context_type(
420 struct bt_ctf_stream_class
*stream_class
,
421 struct bt_ctf_field_type
*event_context_type
);
426 @name Event class children functions
431 @brief Returns the number of event classes contained in the
432 CTF IR stream class \p stream_class.
434 @param[in] stream_class Stream class of which to get the number
435 of children event classes.
436 @returns Number of children event classes
437 contained in \p stream_class, or
438 a negative value on error.
440 @prenotnull{stream_class}
441 @postrefcountsame{stream_class}
443 extern int bt_ctf_stream_class_get_event_class_count(
444 struct bt_ctf_stream_class
*stream_class
);
447 @brief Returns the event class at index \p index in the CTF IR stream
448 class \p stream_class.
450 @param[in] stream_class Stream class of which to get the event class.
451 @param[in] index Index of the event class to find.
452 @returns Event class at index \p index, or \c NULL
455 @prenotnull{stream_class}
456 @pre \p index is lesser than the number of event classes contained in the
457 stream class \p stream_class (see
458 bt_ctf_stream_class_get_event_class_count()).
459 @postrefcountsame{stream_class}
460 @postsuccessrefcountretinc
462 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
464 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
467 extern struct bt_ctf_event_class
*bt_ctf_stream_class_get_event_class(
468 struct bt_ctf_stream_class
*stream_class
, int index
);
471 @brief Returns the event class named \c name found in the CTF IR stream
472 class \p stream_class.
474 @param[in] stream_class Stream class of which to get the event class.
475 @param[in] name Name of the event class to find.
476 @returns Event class named \p name, or \c NULL
479 @prenotnull{stream_class}
481 @postrefcountsame{stream_class}
482 @postsuccessrefcountretinc
484 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
487 extern struct bt_ctf_event_class
*bt_ctf_stream_class_get_event_class_by_name(
488 struct bt_ctf_stream_class
*stream_class
, const char *name
);
491 @brief Returns the event class with ID \c id found in the CTF IR stream
492 class \p stream_class.
494 @param[in] stream_class Stream class of which to get the event class.
495 @param[in] id ID of the event class to find.
496 @returns Event class with ID \p id, or \c NULL
499 @prenotnull{stream_class}
500 @postrefcountsame{stream_class}
501 @postsuccessrefcountretinc
503 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
506 extern struct bt_ctf_event_class
*bt_ctf_stream_class_get_event_class_by_id(
507 struct bt_ctf_stream_class
*stream_class
, uint32_t id
);
510 @brief Adds the CTF IR event class \p event_class to the
511 CTF IR stream class \p stream_class.
513 On success, \p event_class becomes the child of \p stream_class.
515 You can only add a given event class to one stream class.
517 You can call this function even if \p stream_class is frozen. Adding
518 event classes is the only operation that is permitted
519 on a frozen stream class.
521 @param[in] stream_class Stream class to which to add \p event_class.
522 @param[in] event_class Event class to add to \p stream_class.
523 @returns 0 on success, or a negative value on error.
525 @prenotnull{stream_class}
526 @prenotnull{event_class}
528 @postrefcountsame{stream_class}
529 @postsuccessrefcountinc{event_class}
530 @postsuccessfrozen{event_class}
532 extern int bt_ctf_stream_class_add_event_class(
533 struct bt_ctf_stream_class
*stream_class
,
534 struct bt_ctf_event_class
*event_class
);
544 @brief Accepts the visitor \p visitor to visit the hierarchy of the
545 CTF IR stream class \p stream_class.
547 This function traverses the hierarchy of \p stream_class in pre-order
548 and calls \p visitor on each element.
550 The stream class itself is visited first, and then all its children
553 @param[in] stream_class Stream class to visit.
554 @param[in] visitor Visiting function.
555 @param[in] data User data.
556 @returns 0 on success, or a negative value on error.
558 @prenotnull{stream_class}
561 extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class
*stream_class
,
562 bt_ctf_visitor visitor
, void *data
);
568 // TODO: document for writer
569 extern struct bt_ctf_clock
*bt_ctf_stream_class_get_clock(
570 struct bt_ctf_stream_class
*stream_class
);
576 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */
This page took 0.041426 seconds and 4 git commands to generate.