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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-stream Stream
29 A <strong><em>stream</em></strong> is a conceptual
30 \ref api-msg-seq "sequence of messages" within a \bt_trace:
32 @image html trace-structure.png
34 In the illustration above, notice that:
36 - A \bt_stream is a conceptual sequence of \bt_p_msg.
38 The sequence always starts with a \bt_sb_msg and ends with a
41 - A stream is an instance of a \bt_stream_cls.
43 - A \bt_trace contains one or more streams.
45 A stream is a \ref api-tir "trace IR" data object.
47 A stream is said to be a \em conceptual sequence of messages because the
48 stream object itself does not contain messages: it only represents a
49 common timeline to which messages are associated.
51 \bt_cp_comp exchange messages, within a trace processing \bt_graph,
52 which can belong to different streams, as long as the stream clocks are
53 \ref api-tir-clock-cls-origin "correlatable".
55 A typical use case for streams is to use one for each traced CPU. Then
56 the messages related to a given stream are the ones which occurred on a
57 given CPU. Other schemes are possible: they are completely
58 application-specific, and \bt_name does not enforce any specific
59 stream arrangement pattern.
61 A \bt_trace contains streams. All the streams of a
62 given trace, for a given stream class, have unique numeric IDs. Borrow
63 the trace which contains a stream with bt_stream_borrow_trace() or
64 bt_stream_borrow_trace_const().
66 A \bt_stream can conceptually contain a default clock if its class
67 has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
68 There's no function to access a stream's default clock because it's
69 a stateful object: \bt_p_msg cannot refer to stateful objects
70 because they must not change while being transported from one
71 \bt_comp to the other. Instead of having a stream default clock object,
72 \bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
73 stream's default clock (a \bt_clock_cls instance):
75 @image html clocks.png
77 In the illustration above, notice that:
79 - Streams (horizontal blue rectangles) are instances of a
80 \bt_stream_cls (orange).
82 - A stream class has a default \bt_clock_cls (orange bell alarm clock).
84 - Each stream has a default clock (yellow bell alarm clock): this is an
85 instance of the stream's class's default clock class.
87 - Each \bt_msg (objects in blue stream rectangles) created for a given
88 stream has a default \bt_cs (yellow star): this is a snapshot of the
89 stream's default clock.
91 In other words, a default clock snapshot contains the value of the
92 stream's default clock when this message occurred.
98 If bt_stream_class_assigns_automatic_stream_id() returns
99 #BT_TRUE (the default) for the stream class to use
101 <dd>Use bt_stream_create().</dd>
104 If bt_stream_class_assigns_automatic_stream_id() returns
105 #BT_FALSE for the stream class to use
107 <dd>Use bt_stream_create_with_id().</dd>
110 A stream is a \ref api-fund-shared-object "shared object": get a
111 new reference with bt_stream_get_ref() and put an existing
112 reference with bt_stream_put_ref().
114 Some library functions \ref api-fund-freezing "freeze" streams on
115 success. The documentation of those functions indicate this
118 The type of a stream is #bt_stream.
122 A stream has the following property:
125 <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
127 Numeric ID, unique amongst the numeric IDs of the stream's
128 \bt_trace's streams for a given \bt_stream_cls. In other words,
129 two streams which belong to the same trace can have the same numeric
130 ID if they aren't instances of the same class.
132 Depending on whether or not the stream's class
133 automatically assigns stream IDs
134 (see bt_stream_class_assigns_automatic_stream_id()),
135 set the stream's numeric ID on creation with
136 bt_stream_create() or bt_stream_create_with_id().
138 You cannot change the numeric ID once the stream is created.
140 Get a stream's numeric ID with bt_stream_get_id().
143 <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
147 Use bt_stream_set_name() and bt_stream_get_name().
151 \anchor api-tir-stream-prop-user-attrs
152 \bt_dt_opt User attributes
155 User attributes of the stream.
157 User attributes are custom attributes attached to a stream.
159 Use bt_stream_set_user_attributes(),
160 bt_stream_borrow_user_attributes(), and
161 bt_stream_borrow_user_attributes_const().
172 @typedef struct bt_stream bt_stream;
187 Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
188 adds it to the \bt_trace \bt_p{trace}.
190 This function instantiates \bt_p{stream_class}.
194 Only use this function if
197 bt_stream_class_assigns_automatic_stream_id(stream_class)
202 Otherwise, use bt_stream_create_with_id().
205 On success, the returned stream has the following property values:
212 <td>\ref api-tir-stream-prop-id "Numeric ID"
213 <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
215 <td>\ref api-tir-stream-prop-name "Name"
218 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
219 <td>Empty \bt_map_val
222 @param[in] stream_class
223 Stream class from which to create the stream.
225 Trace to add the created stream to.
228 New stream reference, or \c NULL on memory error.
230 @bt_pre_not_null{stream_class}
232 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
234 @bt_pre_not_null{trace}
236 @bt_post_success_frozen{stream_class}
237 @bt_post_success_frozen{trace}
239 @sa bt_stream_create_with_id() —
240 Creates a stream with a specific numeric ID and adds it to a
243 extern bt_stream
*bt_stream_create(bt_stream_class
*stream_class
,
248 Creates a stream with the numeric ID \bt_p{id}
249 from the \bt_stream_cls \bt_p{stream_class} and adds
250 it to the \bt_trace \bt_p{trace}.
252 This function instantiates \bt_p{stream_class}.
256 Only use this function if
259 bt_stream_class_assigns_automatic_stream_id(stream_class)
264 Otherwise, use bt_stream_create().
267 On success, the returned stream has the following property values:
274 <td>\ref api-tir-stream-prop-id "Numeric ID"
277 <td>\ref api-tir-stream-prop-name "Name"
280 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
281 <td>Empty \bt_map_val
284 @param[in] stream_class
285 Stream class from which to create the stream.
287 Trace to add the created stream to.
289 Numeric ID of the stream to create and add to \bt_p{trace}.
292 New stream reference, or \c NULL on memory error.
294 @bt_pre_not_null{stream_class}
296 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
298 @bt_pre_not_null{trace}
300 \bt_p{trace} does not contain an instance of \bt_p{stream_class}
301 with the numeric ID \bt_p{id}.
303 @bt_post_success_frozen{stream_class}
304 @bt_post_success_frozen{trace}
306 @sa bt_stream_create() —
307 Creates a stream with an automatic numeric ID and adds it to a
310 extern bt_stream
*bt_stream_create_with_id(
311 bt_stream_class
*stream_class
,
312 bt_trace
*trace
, uint64_t id
);
323 Borrows the \ref api-tir-stream-cls "class" of the stream
327 Stream of which to borrow the class.
330 \em Borrowed reference of the class of \bt_p{stream}.
332 @bt_pre_not_null{stream}
334 @sa bt_stream_borrow_class_const() —
335 \c const version of this function.
337 extern bt_stream_class
*bt_stream_borrow_class(bt_stream
*stream
);
341 Borrows the \ref api-tir-stream-cls "class" of the stream
342 \bt_p{stream} (\c const version).
344 See bt_stream_borrow_class().
346 extern const bt_stream_class
*bt_stream_borrow_class_const(
347 const bt_stream
*stream
);
358 Borrows the \bt_trace which contains the stream \bt_p{stream}.
361 Stream of which to borrow the trace containing it.
364 \em Borrowed reference of the trace containing \bt_p{stream}.
366 @bt_pre_not_null{stream}
368 @sa bt_stream_borrow_trace_const() —
369 \c const version of this function.
371 extern bt_trace
*bt_stream_borrow_trace(bt_stream
*stream
);
375 Borrows the \bt_trace which contains the stream \bt_p{stream}
378 See bt_stream_borrow_trace().
380 extern const bt_trace
*bt_stream_borrow_trace_const(
381 const bt_stream
*stream
);
392 Returns the numeric ID of the stream \bt_p{stream}.
394 See the \ref api-tir-stream-prop-id "numeric ID" property.
397 Stream of which to get the numeric ID.
400 Numeric ID of \bt_p{stream}.
402 @bt_pre_not_null{stream}
404 @sa bt_stream_create_with_id() —
405 Creates a stream with a specific numeric ID and adds it to a
408 extern uint64_t bt_stream_get_id(const bt_stream
*stream
);
412 Status codes for bt_stream_set_name().
414 typedef enum bt_stream_set_name_status
{
419 BT_STREAM_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
425 BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
426 } bt_stream_set_name_status
;
430 Sets the name of the stream \bt_p{stream} to
431 a copy of \bt_p{name}.
433 See the \ref api-tir-stream-prop-name "name" property.
436 Stream of which to set the name to \bt_p{name}.
438 New name of \bt_p{stream} (copied).
440 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
442 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
445 @bt_pre_not_null{stream}
447 @bt_pre_not_null{name}
449 @sa bt_stream_get_name() —
450 Returns the name of a stream.
452 extern bt_stream_set_name_status
bt_stream_set_name(bt_stream
*stream
,
457 Returns the name of the stream \bt_p{stream}.
459 See the \ref api-tir-stream-prop-name "name" property.
461 If \bt_p{stream} has no name, this function returns \c NULL.
464 Stream of which to get the name.
468 Name of \bt_p{stream}, or \c NULL if none.
470 The returned pointer remains valid as long as \bt_p{stream}
474 @bt_pre_not_null{stream}
476 @sa bt_stream_class_set_name() —
477 Sets the name of a stream.
479 extern const char *bt_stream_get_name(const bt_stream
*stream
);
483 Sets the user attributes of the stream \bt_p{stream} to
484 \bt_p{user_attributes}.
486 See the \ref api-tir-stream-prop-user-attrs "user attributes"
490 When you create a default stream with bt_stream_create()
491 or bt_stream_create_with_id(), the stream's initial user
492 attributes is an empty \bt_map_val. Therefore you can borrow it with
493 bt_stream_borrow_user_attributes() and fill it directly
494 instead of setting a new one with this function.
497 Stream of which to set the user attributes to
498 \bt_p{user_attributes}.
499 @param[in] user_attributes
500 New user attributes of \bt_p{stream}.
502 @bt_pre_not_null{stream}
504 @bt_pre_not_null{user_attributes}
505 @bt_pre_is_map_val{user_attributes}
507 @sa bt_stream_borrow_user_attributes() —
508 Borrows the user attributes of a stream.
510 extern void bt_stream_set_user_attributes(
511 bt_stream
*stream
, const bt_value
*user_attributes
);
515 Borrows the user attributes of the stream \bt_p{stream}.
517 See the \ref api-tir-stream-prop-user-attrs "user attributes"
521 When you create a default stream with bt_stream_create()
522 or bt_stream_create_with_id(), the stream's initial user
523 attributes is an empty \bt_map_val.
526 Stream from which to borrow the user attributes.
529 User attributes of \bt_p{stream} (a \bt_map_val).
531 @bt_pre_not_null{stream}
533 @sa bt_stream_set_user_attributes() —
534 Sets the user attributes of a stream.
535 @sa bt_stream_borrow_user_attributes_const() —
536 \c const version of this function.
538 extern bt_value
*bt_stream_borrow_user_attributes(bt_stream
*stream
);
542 Borrows the user attributes of the stream \bt_p{stream}
545 See bt_stream_borrow_user_attributes().
547 extern const bt_value
*bt_stream_borrow_user_attributes_const(
548 const bt_stream
*stream
);
553 @name Reference count
559 Increments the \ref api-fund-shared-object "reference count" of
560 the stream \bt_p{stream}.
564 Stream of which to increment the reference count.
569 @sa bt_stream_put_ref() —
570 Decrements the reference count of a stream.
572 extern void bt_stream_get_ref(const bt_stream
*stream
);
576 Decrements the \ref api-fund-shared-object "reference count" of
577 the stream \bt_p{stream}.
581 Stream of which to decrement the reference count.
586 @sa bt_stream_get_ref() —
587 Increments the reference count of a stream.
589 extern void bt_stream_put_ref(const bt_stream
*stream
);
593 Decrements the reference count of the stream
594 \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
598 Stream of which to decrement the reference count.
603 @bt_pre_assign_expr{_stream}
605 #define BT_STREAM_PUT_REF_AND_RESET(_stream) \
607 bt_stream_put_ref(_stream); \
613 Decrements the reference count of the stream \bt_p{_dst}, sets
614 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
616 This macro effectively moves a stream reference from the expression
617 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
618 \bt_p{_dst} reference.
622 Destination expression.
633 @bt_pre_assign_expr{_dst}
634 @bt_pre_assign_expr{_src}
636 #define BT_STREAM_MOVE_REF(_dst, _src) \
638 bt_stream_put_ref(_dst); \
651 #endif /* BABELTRACE2_TRACE_IR_STREAM_H */