2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_STREAM_H
8 #define BABELTRACE2_TRACE_IR_STREAM_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-stream Stream
31 A <strong><em>stream</em></strong> is a conceptual
32 \ref api-msg-seq "sequence of messages" within a \bt_trace:
34 @image html trace-structure.png
36 In the illustration above, notice that:
38 - A \bt_stream is a conceptual sequence of \bt_p_msg.
40 The sequence always starts with a \bt_sb_msg and ends with a
43 - A stream is an instance of a \bt_stream_cls.
45 - A \bt_trace contains one or more streams.
47 A stream is a \ref api-tir "trace IR" data object.
49 A stream is said to be a \em conceptual sequence of messages because the
50 stream object itself does not contain messages: it only represents a
51 common timeline to which messages are associated.
53 \bt_cp_comp exchange messages, within a trace processing \bt_graph,
54 which can belong to different streams, as long as the stream clocks are
55 \ref api-tir-clock-cls-origin "correlatable".
57 A typical use case for streams is to use one for each traced CPU. Then
58 the messages related to a given stream are the ones which occurred on a
59 given CPU. Other schemes are possible: they are completely
60 application-specific, and \bt_name does not enforce any specific
61 stream arrangement pattern.
63 A \bt_trace contains streams. All the streams of a
64 given trace, for a given stream class, have unique numeric IDs. Borrow
65 the trace which contains a stream with bt_stream_borrow_trace() or
66 bt_stream_borrow_trace_const().
68 A \bt_stream can conceptually contain a default clock if its class
69 has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
70 There's no function to access a stream's default clock because it's
71 a stateful object: \bt_p_msg cannot refer to stateful objects
72 because they must not change while being transported from one
73 \bt_comp to the other. Instead of having a stream default clock object,
74 \bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
75 stream's default clock (a \bt_clock_cls instance):
77 @image html clocks.png
79 In the illustration above, notice that:
81 - Streams (horizontal blue rectangles) are instances of a
82 \bt_stream_cls (orange).
84 - A stream class has a default \bt_clock_cls (orange bell alarm clock).
86 - Each stream has a default clock (yellow bell alarm clock): this is an
87 instance of the stream's class's default clock class.
89 - Each \bt_msg (objects in blue stream rectangles) created for a given
90 stream has a default \bt_cs (yellow star): this is a snapshot of the
91 stream's default clock.
93 In other words, a default clock snapshot contains the value of the
94 stream's default clock when this message occurred.
100 If bt_stream_class_assigns_automatic_stream_id() returns
101 #BT_TRUE (the default) for the stream class to use
103 <dd>Use bt_stream_create().</dd>
106 If bt_stream_class_assigns_automatic_stream_id() returns
107 #BT_FALSE for the stream class to use
109 <dd>Use bt_stream_create_with_id().</dd>
112 A stream is a \ref api-fund-shared-object "shared object": get a
113 new reference with bt_stream_get_ref() and put an existing
114 reference with bt_stream_put_ref().
116 Some library functions \ref api-fund-freezing "freeze" streams on
117 success. The documentation of those functions indicate this
120 The type of a stream is #bt_stream.
124 A stream has the following property:
127 <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
129 Numeric ID, unique amongst the numeric IDs of the stream's
130 \bt_trace's streams for a given \bt_stream_cls. In other words,
131 two streams which belong to the same trace can have the same numeric
132 ID if they aren't instances of the same class.
134 Depending on whether or not the stream's class
135 automatically assigns stream IDs
136 (see bt_stream_class_assigns_automatic_stream_id()),
137 set the stream's numeric ID on creation with
138 bt_stream_create() or bt_stream_create_with_id().
140 You cannot change the numeric ID once the stream is created.
142 Get a stream's numeric ID with bt_stream_get_id().
145 <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
149 Use bt_stream_set_name() and bt_stream_get_name().
153 \anchor api-tir-stream-prop-user-attrs
154 \bt_dt_opt User attributes
157 User attributes of the stream.
159 User attributes are custom attributes attached to a stream.
161 Use bt_stream_set_user_attributes(),
162 bt_stream_borrow_user_attributes(), and
163 bt_stream_borrow_user_attributes_const().
174 @typedef struct bt_stream bt_stream;
189 Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
190 adds it to the \bt_trace \bt_p{trace}.
192 This function instantiates \bt_p{stream_class}.
196 Only use this function if
199 bt_stream_class_assigns_automatic_stream_id(stream_class)
204 Otherwise, use bt_stream_create_with_id().
207 On success, the returned stream has the following property values:
214 <td>\ref api-tir-stream-prop-id "Numeric ID"
215 <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
217 <td>\ref api-tir-stream-prop-name "Name"
220 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
221 <td>Empty \bt_map_val
224 @param[in] stream_class
225 Stream class from which to create the stream.
227 Trace to add the created stream to.
230 New stream reference, or \c NULL on memory error.
232 @bt_pre_not_null{stream_class}
234 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
236 @bt_pre_not_null{trace}
238 @bt_post_success_frozen{stream_class}
239 @bt_post_success_frozen{trace}
241 @sa bt_stream_create_with_id() —
242 Creates a stream with a specific numeric ID and adds it to a
245 extern bt_stream
*bt_stream_create(bt_stream_class
*stream_class
,
250 Creates a stream with the numeric ID \bt_p{id}
251 from the \bt_stream_cls \bt_p{stream_class} and adds
252 it to the \bt_trace \bt_p{trace}.
254 This function instantiates \bt_p{stream_class}.
258 Only use this function if
261 bt_stream_class_assigns_automatic_stream_id(stream_class)
266 Otherwise, use bt_stream_create().
269 On success, the returned stream has the following property values:
276 <td>\ref api-tir-stream-prop-id "Numeric ID"
279 <td>\ref api-tir-stream-prop-name "Name"
282 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
283 <td>Empty \bt_map_val
286 @param[in] stream_class
287 Stream class from which to create the stream.
289 Trace to add the created stream to.
291 Numeric ID of the stream to create and add to \bt_p{trace}.
294 New stream reference, or \c NULL on memory error.
296 @bt_pre_not_null{stream_class}
298 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
300 @bt_pre_not_null{trace}
302 \bt_p{trace} does not contain an instance of \bt_p{stream_class}
303 with the numeric ID \bt_p{id}.
305 @bt_post_success_frozen{stream_class}
306 @bt_post_success_frozen{trace}
308 @sa bt_stream_create() —
309 Creates a stream with an automatic numeric ID and adds it to a
312 extern bt_stream
*bt_stream_create_with_id(
313 bt_stream_class
*stream_class
,
314 bt_trace
*trace
, uint64_t id
);
325 Borrows the \ref api-tir-stream-cls "class" of the stream
329 Stream of which to borrow the class.
332 \em Borrowed reference of the class of \bt_p{stream}.
334 @bt_pre_not_null{stream}
336 @sa bt_stream_borrow_class_const() —
337 \c const version of this function.
339 extern bt_stream_class
*bt_stream_borrow_class(bt_stream
*stream
);
343 Borrows the \ref api-tir-stream-cls "class" of the stream
344 \bt_p{stream} (\c const version).
346 See bt_stream_borrow_class().
348 extern const bt_stream_class
*bt_stream_borrow_class_const(
349 const bt_stream
*stream
);
360 Borrows the \bt_trace which contains the stream \bt_p{stream}.
363 Stream of which to borrow the trace containing it.
366 \em Borrowed reference of the trace containing \bt_p{stream}.
368 @bt_pre_not_null{stream}
370 @sa bt_stream_borrow_trace_const() —
371 \c const version of this function.
373 extern bt_trace
*bt_stream_borrow_trace(bt_stream
*stream
);
377 Borrows the \bt_trace which contains the stream \bt_p{stream}
380 See bt_stream_borrow_trace().
382 extern const bt_trace
*bt_stream_borrow_trace_const(
383 const bt_stream
*stream
);
394 Returns the numeric ID of the stream \bt_p{stream}.
396 See the \ref api-tir-stream-prop-id "numeric ID" property.
399 Stream of which to get the numeric ID.
402 Numeric ID of \bt_p{stream}.
404 @bt_pre_not_null{stream}
406 @sa bt_stream_create_with_id() —
407 Creates a stream with a specific numeric ID and adds it to a
410 extern uint64_t bt_stream_get_id(const bt_stream
*stream
);
414 Status codes for bt_stream_set_name().
416 typedef enum bt_stream_set_name_status
{
421 BT_STREAM_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
427 BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
428 } bt_stream_set_name_status
;
432 Sets the name of the stream \bt_p{stream} to
433 a copy of \bt_p{name}.
435 See the \ref api-tir-stream-prop-name "name" property.
438 Stream of which to set the name to \bt_p{name}.
440 New name of \bt_p{stream} (copied).
442 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
444 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
447 @bt_pre_not_null{stream}
449 @bt_pre_not_null{name}
451 @sa bt_stream_get_name() —
452 Returns the name of a stream.
454 extern bt_stream_set_name_status
bt_stream_set_name(bt_stream
*stream
,
459 Returns the name of the stream \bt_p{stream}.
461 See the \ref api-tir-stream-prop-name "name" property.
463 If \bt_p{stream} has no name, this function returns \c NULL.
466 Stream of which to get the name.
470 Name of \bt_p{stream}, or \c NULL if none.
472 The returned pointer remains valid as long as \bt_p{stream}
476 @bt_pre_not_null{stream}
478 @sa bt_stream_class_set_name() —
479 Sets the name of a stream.
481 extern const char *bt_stream_get_name(const bt_stream
*stream
);
485 Sets the user attributes of the stream \bt_p{stream} to
486 \bt_p{user_attributes}.
488 See the \ref api-tir-stream-prop-user-attrs "user attributes"
492 When you create a default stream with bt_stream_create()
493 or bt_stream_create_with_id(), the stream's initial user
494 attributes is an empty \bt_map_val. Therefore you can borrow it with
495 bt_stream_borrow_user_attributes() and fill it directly
496 instead of setting a new one with this function.
499 Stream of which to set the user attributes to
500 \bt_p{user_attributes}.
501 @param[in] user_attributes
502 New user attributes of \bt_p{stream}.
504 @bt_pre_not_null{stream}
506 @bt_pre_not_null{user_attributes}
507 @bt_pre_is_map_val{user_attributes}
509 @sa bt_stream_borrow_user_attributes() —
510 Borrows the user attributes of a stream.
512 extern void bt_stream_set_user_attributes(
513 bt_stream
*stream
, const bt_value
*user_attributes
);
517 Borrows the user attributes of the stream \bt_p{stream}.
519 See the \ref api-tir-stream-prop-user-attrs "user attributes"
523 When you create a default stream with bt_stream_create()
524 or bt_stream_create_with_id(), the stream's initial user
525 attributes is an empty \bt_map_val.
528 Stream from which to borrow the user attributes.
531 User attributes of \bt_p{stream} (a \bt_map_val).
533 @bt_pre_not_null{stream}
535 @sa bt_stream_set_user_attributes() —
536 Sets the user attributes of a stream.
537 @sa bt_stream_borrow_user_attributes_const() —
538 \c const version of this function.
540 extern bt_value
*bt_stream_borrow_user_attributes(bt_stream
*stream
);
544 Borrows the user attributes of the stream \bt_p{stream}
547 See bt_stream_borrow_user_attributes().
549 extern const bt_value
*bt_stream_borrow_user_attributes_const(
550 const bt_stream
*stream
);
555 @name Reference count
561 Increments the \ref api-fund-shared-object "reference count" of
562 the stream \bt_p{stream}.
566 Stream of which to increment the reference count.
571 @sa bt_stream_put_ref() —
572 Decrements the reference count of a stream.
574 extern void bt_stream_get_ref(const bt_stream
*stream
);
578 Decrements the \ref api-fund-shared-object "reference count" of
579 the stream \bt_p{stream}.
583 Stream of which to decrement the reference count.
588 @sa bt_stream_get_ref() —
589 Increments the reference count of a stream.
591 extern void bt_stream_put_ref(const bt_stream
*stream
);
595 Decrements the reference count of the stream
596 \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
600 Stream of which to decrement the reference count.
605 @bt_pre_assign_expr{_stream}
607 #define BT_STREAM_PUT_REF_AND_RESET(_stream) \
609 bt_stream_put_ref(_stream); \
615 Decrements the reference count of the stream \bt_p{_dst}, sets
616 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
618 This macro effectively moves a stream reference from the expression
619 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
620 \bt_p{_dst} reference.
624 Destination expression.
635 @bt_pre_assign_expr{_dst}
636 @bt_pre_assign_expr{_src}
638 #define BT_STREAM_MOVE_REF(_dst, _src) \
640 bt_stream_put_ref(_dst); \
653 #endif /* BABELTRACE2_TRACE_IR_STREAM_H */