lib: metadata: transform fast path precond. checks to BT_ASSERT_PRE()
[babeltrace.git] / include / babeltrace / ctf-ir / stream-class.h
1 #ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
2 #define BABELTRACE_CTF_IR_STREAM_CLASS_H
3
4 /*
5 * BabelTrace - CTF IR: Stream Class
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 #include <stdint.h>
34
35 /* For bt_visitor */
36 #include <babeltrace/ctf-ir/visitor.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /**
43 @defgroup ctfirstreamclass CTF IR stream class
44 @ingroup ctfir
45 @brief CTF IR stream class.
46
47 @code
48 #include <babeltrace/ctf-ir/stream-class.h>
49 @endcode
50
51 @note
52 See \ref ctfwriterstreamclass which documents additional CTF IR stream
53 class functions exclusive to the CTF writer mode.
54
55 A CTF IR <strong><em>stream class</em></strong> is a template that you
56 can use to create concrete \link ctfirstream CTF IR streams\endlink.
57
58 A stream class has the following properties, both of which \em must
59 be unique amongst all the stream classes contained in the same
60 \link ctfirtraceclass CTF IR trace class\endlink:
61
62 - A \b name.
63 - A numeric \b ID.
64
65 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
66 contains zero or more stream classes,
67 and a stream class contains zero or more
68 \link ctfireventclass event classes\endlink.
69 You can add an event class
70 to a stream class with bt_stream_class_add_event_class().
71 You can add a stream class to a trace class with
72 bt_trace_add_stream_class().
73
74 A stream class owns three \link ctfirfieldtypes field types\endlink:
75
76 - An optional <strong>stream packet context</strong> field type, which
77 represents the \c stream.packet.context CTF scope.
78 - An optional <strong>stream event header</strong> field type, which
79 represents the \c stream.event.header CTF scope.
80 - An optional <strong>stream event context</strong> field type, which
81 represents the \c stream.event.context CTF scope.
82
83 Those three field types \em must be structure field types as of
84 Babeltrace \btversion.
85
86 As per the CTF specification, the event header field type \em must
87 contain a field named \c id if the stream class contains more than one
88 event class.
89
90 As a reminder, here's the structure of a CTF packet:
91
92 @imgpacketstructure
93
94 Before you can create a stream from a stream class with
95 bt_stream_create(), you \em must add the prepared stream class to a
96 trace class by calling bt_trace_add_stream_class().
97
98 As with any Babeltrace object, CTF IR stream class objects have
99 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
100 counts</a>. See \ref refs to learn more about the reference counting
101 management of Babeltrace objects.
102
103 The following functions \em freeze their stream class parameter on
104 success:
105
106 - bt_trace_add_stream_class()
107 - bt_event_create()
108 - bt_writer_create_stream()
109 (\link ctfwriter CTF writer\endlink mode only)
110
111 You cannot modify a frozen stream class: it is considered immutable,
112 except for:
113
114 - Adding an event class to it with
115 bt_stream_class_add_event_class(). If the stream class's parent
116 \link ctfirtraceclass trace class\endlink is static, however,
117 you cannot call bt_stream_class_add_event_class()
118 (see bt_trace_is_static() and bt_trace_set_is_static()).
119 - \link refs Reference counting\endlink.
120
121 @sa ctfirstream
122 @sa ctfireventclass
123 @sa ctfirtraceclass
124 @sa ctfwriterstreamclass
125
126 @file
127 @brief CTF IR stream class type and functions.
128 @sa ctfirstreamclass
129
130 @addtogroup ctfirstreamclass
131 @{
132 */
133
134 /**
135 @struct bt_stream_class
136 @brief A CTF IR stream class.
137 @sa ctfirstreamclass
138 */
139 struct bt_stream_class;
140 struct bt_event_class;
141 struct bt_clock;
142
143 /**
144 @name Creation and parent access functions
145 @{
146 */
147
148 /**
149 @brief Creates an empty CTF IR stream class named \p name, or an
150 unnamed empty stream class if \p name is \c NULL.
151
152 On success, the packet context, event header, and event context field
153 types are empty structure field types. You can modify those default
154 field types after the stream class is created with
155 bt_stream_class_set_packet_context_type(),
156 bt_stream_class_set_event_header_type(), and
157 bt_stream_class_set_event_context_type().
158
159 @param[in] name Name of the stream class to create (copied on success),
160 or \c NULL to create an unnamed stream class.
161 @returns Created empty stream class, or \c NULL on error.
162
163 @postsuccessrefcountret1
164
165 @sa bt_stream_class_create(): Creates a default stream class.
166 */
167 extern struct bt_stream_class *bt_stream_class_create_empty(
168 const char *name);
169
170 /**
171 @brief Creates a default CTF IR stream class named \p name­, or a
172 default unnamed stream class if \p name is \c NULL.
173
174 On success, the packet context field type of the created stream class
175 has the following fields:
176
177 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
178 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
179 - <code>content_size</code>: a 64-bit unsigned integer field type.
180 - <code>packet_size</code>: a 64-bit unsigned integer field type.
181 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
182
183 On success, the event header field type of the created stream class
184 has the following fields:
185
186 - <code>code</code>: a 32-bit unsigned integer field type.
187 - <code>timestamp</code>: a 64-bit unsigned integer field type.
188
189 You can modify those default field types after the stream class is
190 created with bt_stream_class_set_packet_context_type() and
191 bt_stream_class_set_event_header_type().
192
193 @param[in] name Name of the stream class to create (copied on success),
194 or \c NULL to create an unnamed stream class.
195 @returns Created default stream class, or \c NULL on error.
196
197 @postsuccessrefcountret1
198
199 @sa bt_stream_class_create_empty(): Creates an empty stream class.
200 */
201 extern struct bt_stream_class *bt_stream_class_create(const char *name);
202
203 /**
204 @brief Returns the parent CTF IR trace class of the CTF IR stream
205 class \p stream_class.
206
207 It is possible that the stream class was not added to a trace class
208 yet, in which case this function returns \c NULL. You can add a
209 stream class to a trace class with
210 bt_trace_add_stream_class().
211
212 @param[in] stream_class Stream class of which to get the parent
213 trace class.
214 @returns Parent trace class of \p stream_class,
215 or \c NULL if \p stream_class was not
216 added to a trace class yet or on error.
217
218 @prenotnull{stream_class}
219 @postrefcountsame{stream_class}
220 @postsuccessrefcountretinc
221
222 @sa bt_trace_add_stream_class(): Add a stream class to
223 a trace class.
224 */
225 extern struct bt_trace *bt_stream_class_get_trace(
226 struct bt_stream_class *stream_class);
227
228 /** @} */
229
230 /**
231 @name Properties functions
232 @{
233 */
234
235 /**
236 @brief Returns the name of the CTF IR stream class \p stream_class.
237
238 On success, \p stream_class remains the sole owner of the returned
239 string.
240
241 @param[in] stream_class Stream class of which to get the name.
242 @returns Name of stream class \p stream_class, or
243 \c NULL if \p stream_class is unnamed or
244 on error.
245
246 @prenotnull{stream_class}
247 @postrefcountsame{stream_class}
248
249 @sa bt_stream_class_set_name(): Sets the name of a given
250 stream class.
251 */
252 extern const char *bt_stream_class_get_name(
253 struct bt_stream_class *stream_class);
254
255 /**
256 @brief Sets the name of the CTF IR stream class
257 \p stream_class to \p name, or resets the name of
258 \p stream_class.
259
260 If \p name is not \c NULL, it must be unique amongst the names of all
261 the stream classes of the trace class to which you eventually add
262 \p stream_class.
263
264 @param[in] stream_class Stream class of which to set the name.
265 @param[in] name Name of the stream class (copied on success), or
266 \c NULL to reset the name of \p stream_class
267 (make it unnamed).
268 @returns 0 on success, or a negative value on error.
269
270 @prenotnull{stream_class}
271 @prehot{stream_class}
272 @postrefcountsame{stream_class}
273
274 @sa bt_stream_class_get_name(): Returns the name of a given
275 stream class.
276 */
277 extern int bt_stream_class_set_name(
278 struct bt_stream_class *stream_class, const char *name);
279
280 /**
281 @brief Returns the numeric ID of the CTF IR stream class \p stream_class.
282
283 @param[in] stream_class Stream class of which to get the numeric ID.
284 @returns ID of stream class \p stream_class, or a
285 negative value on error.
286
287 @prenotnull{stream_class}
288 @postrefcountsame{stream_class}
289
290 @sa bt_stream_class_set_id(): Sets the numeric ID of a given
291 stream class.
292 */
293 extern int64_t bt_stream_class_get_id(
294 struct bt_stream_class *stream_class);
295
296 /**
297 @brief Sets the numeric ID of the CTF IR stream class
298 \p stream_class to \p id.
299
300 \p id must be unique amongst the IDs of all the stream classes
301 of the trace class to which you eventually add \p stream_class.
302
303 @param[in] stream_class Stream class of which to set the numeric ID.
304 @param[in] id ID of the stream class.
305 @returns 0 on success, or a negative value on error.
306
307 @prenotnull{stream_class}
308 @prehot{stream_class}
309 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
310 @postrefcountsame{stream_class}
311
312 @sa bt_stream_class_get_id(): Returns the numeric ID of a given
313 stream class.
314 */
315 extern int bt_stream_class_set_id(
316 struct bt_stream_class *stream_class, uint64_t id);
317
318 /** @} */
319
320 /**
321 @name Contained field types functions
322 @{
323 */
324
325 /**
326 @brief Returns the packet context field type of the CTF IR stream class
327 \p stream_class.
328
329 @param[in] stream_class Stream class of which to get the packet
330 context field type.
331 @returns Packet context field type of \p stream_class,
332 or \c NULL if \p stream_class has no packet context
333 field type or on error.
334
335 @prenotnull{stream_class}
336 @postrefcountsame{stream_class}
337 @post <strong>On success, if the return value is a field type</strong>, its
338 reference count is incremented.
339
340 @sa bt_stream_class_set_packet_context_type(): Sets the packet
341 context field type of a given stream class.
342 */
343 extern struct bt_field_type *bt_stream_class_get_packet_context_type(
344 struct bt_stream_class *stream_class);
345
346 /**
347 @brief Sets the packet context field type of the CTF IR stream class
348 \p stream_class to \p packet_context_type, or unsets the current packet
349 context field type from \p stream_class.
350
351 If \p packet_context_type is \c NULL, then this function unsets the current
352 packet context field type from \p stream_class, effectively making
353 \p stream_class a stream class without a packet context field type.
354
355 As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
356 \p packet_context_type \em must be a CTF IR structure field type object.
357
358 @param[in] stream_class Stream class of which to set the packet
359 context field type.
360 @param[in] packet_context_type Packet context field type, or \c NULL to unset
361 the current packet context field type.
362 @returns 0 on success, or a negative value on error.
363
364 @prenotnull{stream_class}
365 @prehot{stream_class}
366 @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
367 structure field type.
368 @postrefcountsame{stream_class}
369 @post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
370 the reference count of \p packet_context_type is incremented.
371
372 @sa bt_stream_class_get_packet_context_type(): Returns the packet
373 context field type of a given stream class.
374 */
375 extern int bt_stream_class_set_packet_context_type(
376 struct bt_stream_class *stream_class,
377 struct bt_field_type *packet_context_type);
378
379 /**
380 @brief Returns the event header field type of the CTF IR stream class
381 \p stream_class.
382
383 @param[in] stream_class Stream class of which to get the event header
384 field type.
385 @returns Event header field type of \p stream_class,
386 or \c NULL if \p stream_class has no event header field
387 type or on error.
388
389 @prenotnull{stream_class}
390 @postrefcountsame{stream_class}
391 @post <strong>On success, if the return value is a field type</strong>, its
392 reference count is incremented.
393
394 @sa bt_stream_class_set_event_header_type(): Sets the event
395 header field type of a given stream class.
396 */
397 extern struct bt_field_type *
398 bt_stream_class_get_event_header_type(
399 struct bt_stream_class *stream_class);
400
401 /**
402 @brief Sets the event header field type of the CTF IR stream class
403 \p stream_class to \p event_header_type, or unsets the current event
404 header field type from \p stream_class.
405
406 If \p event_header_type is \c NULL, then this function unsets the current
407 event header field type from \p stream_class, effectively making \p stream_class
408 a stream class without a event header field type.
409
410 As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
411 \p event_header_type \em must be a CTF IR structure field type object.
412
413 @param[in] stream_class Stream class of which to set the event
414 header field type.
415 @param[in] event_header_type Event header field type, or \c NULL to unset
416 the current event header field type.
417 @returns 0 on success, or a negative value on error.
418
419 @prenotnull{stream_class}
420 @prehot{stream_class}
421 @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
422 structure field type.
423 @postrefcountsame{stream_class}
424 @post <strong>On success, if \p event_header_type is not \c NULL</strong>,
425 the reference count of \p event_header_type is incremented.
426
427 @sa bt_stream_class_get_event_header_type(): Returns the event
428 header field type of a given stream class.
429 */
430 extern int bt_stream_class_set_event_header_type(
431 struct bt_stream_class *stream_class,
432 struct bt_field_type *event_header_type);
433
434 /**
435 @brief Returns the event context field type of the CTF IR stream class
436 \p stream_class.
437
438 @param[in] stream_class Stream class of which to get the event context
439 field type.
440 @returns Event context field type of \p stream_class,
441 or \c NULL if \p stream_class has no event context field
442 type or on error.
443
444 @prenotnull{stream_class}
445 @postrefcountsame{stream_class}
446 @post <strong>On success, if the return value is a field type</strong>,
447 its reference count is incremented.
448
449
450 @sa bt_stream_class_set_event_context_type(): Sets the event
451 context field type of a given stream class.
452 */
453 extern struct bt_field_type *
454 bt_stream_class_get_event_context_type(
455 struct bt_stream_class *stream_class);
456
457 /**
458 @brief Sets the event context field type of the CTF IR stream class
459 \p stream_class to \p event_context_type, or unsets the current event
460 context field type from \p stream_class.
461
462 If \p event_context_type is \c NULL, then this function unsets the current
463 event context field type from \p stream_class, effectively making \p
464 stream_class a stream class without a event context field type.
465
466 As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
467 \p event_context_type \em must be a CTF IR structure field type object.
468
469 @param[in] stream_class Stream class of which to set the packet
470 context field type.
471 @param[in] event_context_type Event context field type, or \c NULL to unset
472 the current event context field type.
473 @returns 0 on success, or a negative value on error.
474
475 @prenotnull{stream_class}
476 @prehot{stream_class}
477 @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
478 structure field type.
479 @postrefcountsame{stream_class}
480 @post <strong>On success, if \p event_context_type is not \c NULL</strong>,
481 the reference count of \p event_context_type is incremented.
482
483 @sa bt_stream_class_get_event_context_type(): Returns the event context
484 field type of a given stream class.
485 */
486 extern int bt_stream_class_set_event_context_type(
487 struct bt_stream_class *stream_class,
488 struct bt_field_type *event_context_type);
489
490 /** @} */
491
492 /**
493 @name Event class children functions
494 @{
495 */
496
497 /**
498 @brief Returns the number of event classes contained in the
499 CTF IR stream class \p stream_class.
500
501 @param[in] stream_class Stream class of which to get the number
502 of children event classes.
503 @returns Number of children event classes
504 contained in \p stream_class, or
505 a negative value on error.
506
507 @prenotnull{stream_class}
508 @postrefcountsame{stream_class}
509 */
510 extern int64_t bt_stream_class_get_event_class_count(
511 struct bt_stream_class *stream_class);
512
513 /**
514 @brief Returns the event class at index \p index in the CTF IR stream
515 class \p stream_class.
516
517 @param[in] stream_class Stream class of which to get the event class.
518 @param[in] index Index of the event class to find.
519 @returns Event class at index \p index, or \c NULL
520 on error.
521
522 @prenotnull{stream_class}
523 @pre \p index is lesser than the number of event classes contained in the
524 stream class \p stream_class (see
525 bt_stream_class_get_event_class_count()).
526 @postrefcountsame{stream_class}
527 @postsuccessrefcountretinc
528
529 @sa bt_stream_class_get_event_class_by_id(): Finds an event class
530 by ID.
531 */
532 extern struct bt_event_class *bt_stream_class_get_event_class_by_index(
533 struct bt_stream_class *stream_class, uint64_t index);
534
535 /**
536 @brief Returns the event class with ID \c id found in the CTF IR stream
537 class \p stream_class.
538
539 @param[in] stream_class Stream class of which to get the event class.
540 @param[in] id ID of the event class to find.
541 @returns Event class with ID \p id, or \c NULL
542 on error.
543
544 @prenotnull{stream_class}
545 @postrefcountsame{stream_class}
546 @postsuccessrefcountretinc
547 */
548 extern struct bt_event_class *bt_stream_class_get_event_class_by_id(
549 struct bt_stream_class *stream_class, uint64_t id);
550
551 /**
552 @brief Adds the CTF IR event class \p event_class to the
553 CTF IR stream class \p stream_class.
554
555 On success, \p event_class becomes the child of \p stream_class.
556
557 You can only add a given event class to one stream class.
558
559 You can call this function even if \p stream_class is frozen. Adding
560 event classes is the only operation that is permitted
561 on a frozen stream class.
562
563 This function tries to resolve the needed
564 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
565 types that are found anywhere in the context or payload field
566 types of \p event_class. If any automatic resolving fails:
567
568 - If the needed field type should be found in one of the root field
569 types of \p event_class or \p stream_class, this function fails.
570 - If \p stream_class is the child of a
571 \link ctfirtraceclass CTF IR trace class\endlink (it was added
572 with bt_trace_add_stream_class()), this function fails.
573 - If \p stream_class is not the child of a trace class yet, the
574 automatic resolving is reported to the next call to
575 bt_trace_add_stream_class() with \p stream_class.
576
577 @param[in] stream_class Stream class to which to add \p event_class.
578 @param[in] event_class Event class to add to \p stream_class.
579 @returns 0 on success, or a negative value on error.
580
581 @prenotnull{stream_class}
582 @prenotnull{event_class}
583 @prehot{event_class}
584 @postrefcountsame{stream_class}
585 @postsuccessrefcountinc{event_class}
586 @postsuccessfrozen{event_class}
587 */
588 extern int bt_stream_class_add_event_class(
589 struct bt_stream_class *stream_class,
590 struct bt_event_class *event_class);
591
592 /** @} */
593
594 /**
595 @name Misc. function
596 @{
597 */
598
599 /**
600 @brief Accepts the visitor \p visitor to visit the hierarchy of the
601 CTF IR stream class \p stream_class.
602
603 This function traverses the hierarchy of \p stream_class in pre-order
604 and calls \p visitor on each element.
605
606 The stream class itself is visited first, and then all its children
607 event classes.
608
609 @param[in] stream_class Stream class to visit.
610 @param[in] visitor Visiting function.
611 @param[in] data User data.
612 @returns 0 on success, or a negative value on error.
613
614 @prenotnull{stream_class}
615 @prenotnull{visitor}
616 */
617 extern int bt_stream_class_visit(struct bt_stream_class *stream_class,
618 bt_visitor visitor, void *data);
619
620 /** @} */
621
622 /** @} */
623
624 /* Pre-2.0 CTF writer compatibility */
625 #define bt_ctf_stream_class bt_stream_class
626 #define bt_ctf_stream_class_create bt_stream_class_create
627 #define bt_ctf_stream_class_add_event_class bt_stream_class_add_event_class
628 #define bt_ctf_stream_class_get_packet_context_type bt_stream_class_get_packet_context_type
629
630 #ifdef __cplusplus
631 }
632 #endif
633
634 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */
This page took 0.042604 seconds and 4 git commands to generate.