1 #ifndef BABELTRACE2_TRACE_IR_STREAM_H
2 #define BABELTRACE2_TRACE_IR_STREAM_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
39 @defgroup api-tir-stream Stream
45 A <strong><em>stream</em></strong> is a conceptual
46 \ref api-msg-seq "sequence of messages" within a \bt_trace:
48 @image html trace-structure.png
50 In the illustration above, notice that:
52 - A \bt_stream is a conceptual sequence of \bt_p_msg.
54 The sequence always starts with a \bt_sb_msg and ends with a
57 - A stream is an instance of a \bt_stream_cls.
59 - A \bt_trace contains one or more streams.
61 A stream is a \ref api-tir "trace IR" data object.
63 A stream is said to be a \em conceptual sequence of messages because the
64 stream object itself does not contain messages: it only represents a
65 common timeline to which messages are associated.
67 \bt_cp_comp exchange messages, within a trace processing \bt_graph,
68 which can belong to different streams, as long as the stream clocks are
69 \ref api-tir-clock-cls-origin "correlatable".
71 A typical use case for streams is to use one for each traced CPU. Then
72 the messages related to a given stream are the ones which occurred on a
73 given CPU. Other schemes are possible: they are completely
74 application-specific, and \bt_name does not enforce any specific
75 stream arrangement pattern.
77 A \bt_trace contains streams. All the streams of a
78 given trace, for a given stream class, have unique numeric IDs. Borrow
79 the trace which contains a stream with bt_stream_borrow_trace() or
80 bt_stream_borrow_trace_const().
82 A \bt_stream can conceptually contain a default clock if its class
83 has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
84 There's no function to access a stream's default clock because it's
85 a stateful object: \bt_p_msg cannot refer to stateful objects
86 because they must not change while being transported from one
87 \bt_comp to the other. Instead of having a stream default clock object,
88 \bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
89 stream's default clock (a \bt_clock_cls instance):
91 @image html clocks.png
93 In the illustration above, notice that:
95 - Streams (horizontal blue rectangles) are instances of a
96 \bt_stream_cls (orange).
98 - A stream class has a default \bt_clock_cls (orange bell alarm clock).
100 - Each stream has a default clock (yellow bell alarm clock): this is an
101 instance of the stream's class's default clock class.
103 - Each \bt_msg (objects in blue stream rectangles) created for a given
104 stream has a default \bt_cs (yellow star): this is a snapshot of the
105 stream's default clock.
107 In other words, a default clock snapshot contains the value of the
108 stream's default clock when this message occurred.
114 If bt_stream_class_assigns_automatic_stream_id() returns
115 #BT_TRUE (the default) for the stream class to use
117 <dd>Use bt_stream_create().</dd>
120 If bt_stream_class_assigns_automatic_stream_id() returns
121 #BT_FALSE for the stream class to use
123 <dd>Use bt_stream_create_with_id().</dd>
126 A stream is a \ref api-fund-shared-object "shared object": get a
127 new reference with bt_stream_get_ref() and put an existing
128 reference with bt_stream_put_ref().
130 Some library functions \ref api-fund-freezing "freeze" streams on
131 success. The documentation of those functions indicate this
134 The type of a stream is #bt_stream.
138 A stream has the following property:
141 <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
143 Numeric ID, unique amongst the numeric IDs of the stream's
144 \bt_trace's streams for a given \bt_stream_cls. In other words,
145 two streams which belong to the same trace can have the same numeric
146 ID if they aren't instances of the same class.
148 Depending on whether or not the stream's class
149 automatically assigns stream IDs
150 (see bt_stream_class_assigns_automatic_stream_id()),
151 set the stream's numeric ID on creation with
152 bt_stream_create() or bt_stream_create_with_id().
154 You cannot change the numeric ID once the stream is created.
156 Get a stream's numeric ID with bt_stream_get_id().
159 <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
163 Use bt_stream_set_name() and bt_stream_get_name().
167 \anchor api-tir-stream-prop-user-attrs
168 \bt_dt_opt User attributes
171 User attributes of the stream.
173 User attributes are custom attributes attached to a stream.
175 Use bt_stream_set_user_attributes(),
176 bt_stream_borrow_user_attributes(), and
177 bt_stream_borrow_user_attributes_const().
188 @typedef struct bt_stream bt_stream;
203 Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
204 adds it to the \bt_trace \bt_p{trace}.
206 This function instantiates \bt_p{stream_class}.
210 Only use this function if
213 bt_stream_class_assigns_automatic_stream_id(stream_class)
218 Otherwise, use bt_stream_create_with_id().
221 On success, the returned stream has the following property values:
228 <td>\ref api-tir-stream-prop-id "Numeric ID"
229 <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
231 <td>\ref api-tir-stream-prop-name "Name"
234 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
235 <td>Empty \bt_map_val
238 @param[in] stream_class
239 Stream class from which to create the stream.
241 Trace to add the created stream to.
244 New stream reference, or \c NULL on memory error.
246 @bt_pre_not_null{stream_class}
248 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
250 @bt_pre_not_null{trace}
252 @bt_post_success_frozen{stream_class}
253 @bt_post_success_frozen{trace}
255 @sa bt_stream_create_with_id() —
256 Creates a stream with a specific numeric ID and adds it to a
259 extern bt_stream
*bt_stream_create(bt_stream_class
*stream_class
,
264 Creates a stream with the numeric ID \bt_p{id}
265 from the \bt_stream_cls \bt_p{stream_class} and adds
266 it to the \bt_trace \bt_p{trace}.
268 This function instantiates \bt_p{stream_class}.
272 Only use this function if
275 bt_stream_class_assigns_automatic_stream_id(stream_class)
280 Otherwise, use bt_stream_create().
283 On success, the returned stream has the following property values:
290 <td>\ref api-tir-stream-prop-id "Numeric ID"
293 <td>\ref api-tir-stream-prop-name "Name"
296 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
297 <td>Empty \bt_map_val
300 @param[in] stream_class
301 Stream class from which to create the stream.
303 Trace to add the created stream to.
305 Numeric ID of the stream to create and add to \bt_p{trace}.
308 New stream reference, or \c NULL on memory error.
310 @bt_pre_not_null{stream_class}
312 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
314 @bt_pre_not_null{trace}
316 \bt_p{trace} does not contain an instance of \bt_p{stream_class}
317 with the numeric ID \bt_p{id}.
319 @bt_post_success_frozen{stream_class}
320 @bt_post_success_frozen{trace}
322 @sa bt_stream_create() —
323 Creates a stream with an automatic numeric ID and adds it to a
326 extern bt_stream
*bt_stream_create_with_id(
327 bt_stream_class
*stream_class
,
328 bt_trace
*trace
, uint64_t id
);
339 Borrows the \ref api-tir-stream-cls "class" of the stream
343 Stream of which to borrow the class.
346 \em Borrowed reference of the class of \bt_p{stream}.
348 @bt_pre_not_null{stream}
350 @sa bt_stream_borrow_class_const() —
351 \c const version of this function.
353 extern bt_stream_class
*bt_stream_borrow_class(bt_stream
*stream
);
357 Borrows the \ref api-tir-stream-cls "class" of the stream
358 \bt_p{stream} (\c const version).
360 See bt_stream_borrow_class().
362 extern const bt_stream_class
*bt_stream_borrow_class_const(
363 const bt_stream
*stream
);
374 Borrows the \bt_trace which contains the stream \bt_p{stream}.
377 Stream of which to borrow the trace containing it.
380 \em Borrowed reference of the trace containing \bt_p{stream}.
382 @bt_pre_not_null{stream}
384 @sa bt_stream_borrow_trace_const() —
385 \c const version of this function.
387 extern bt_trace
*bt_stream_borrow_trace(bt_stream
*stream
);
391 Borrows the \bt_trace which contains the stream \bt_p{stream}
394 See bt_stream_borrow_trace().
396 extern const bt_trace
*bt_stream_borrow_trace_const(
397 const bt_stream
*stream
);
408 Returns the numeric ID of the stream \bt_p{stream}.
410 See the \ref api-tir-stream-prop-id "numeric ID" property.
413 Stream of which to get the numeric ID.
416 Numeric ID of \bt_p{stream}.
418 @bt_pre_not_null{stream}
420 @sa bt_stream_create_with_id() —
421 Creates a stream with a specific numeric ID and adds it to a
424 extern uint64_t bt_stream_get_id(const bt_stream
*stream
);
428 Status codes for bt_stream_set_name().
430 typedef enum bt_stream_set_name_status
{
435 BT_STREAM_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
441 BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
442 } bt_stream_set_name_status
;
446 Sets the name of the stream \bt_p{stream} to
447 a copy of \bt_p{name}.
449 See the \ref api-tir-stream-prop-name "name" property.
452 Stream of which to set the name to \bt_p{name}.
454 New name of \bt_p{stream} (copied).
456 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
458 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
461 @bt_pre_not_null{stream}
463 @bt_pre_not_null{name}
465 @sa bt_stream_get_name() —
466 Returns the name of a stream.
468 extern bt_stream_set_name_status
bt_stream_set_name(bt_stream
*stream
,
473 Returns the name of the stream \bt_p{stream}.
475 See the \ref api-tir-stream-prop-name "name" property.
477 If \bt_p{stream} has no name, this function returns \c NULL.
480 Stream of which to get the name.
484 Name of \bt_p{stream}, or \c NULL if none.
486 The returned pointer remains valid as long as \bt_p{stream}
490 @bt_pre_not_null{stream}
492 @sa bt_stream_class_set_name() —
493 Sets the name of a stream.
495 extern const char *bt_stream_get_name(const bt_stream
*stream
);
499 Sets the user attributes of the stream \bt_p{stream} to
500 \bt_p{user_attributes}.
502 See the \ref api-tir-stream-prop-user-attrs "user attributes"
506 When you create a default stream with bt_stream_create()
507 or bt_stream_create_with_id(), the stream's initial user
508 attributes is an empty \bt_map_val. Therefore you can borrow it with
509 bt_stream_borrow_user_attributes() and fill it directly
510 instead of setting a new one with this function.
513 Stream of which to set the user attributes to
514 \bt_p{user_attributes}.
515 @param[in] user_attributes
516 New user attributes of \bt_p{stream}.
518 @bt_pre_not_null{stream}
520 @bt_pre_not_null{user_attributes}
521 @bt_pre_is_map_val{user_attributes}
523 @sa bt_stream_borrow_user_attributes() —
524 Borrows the user attributes of a stream.
526 extern void bt_stream_set_user_attributes(
527 bt_stream
*stream
, const bt_value
*user_attributes
);
531 Borrows the user attributes of the stream \bt_p{stream}.
533 See the \ref api-tir-stream-prop-user-attrs "user attributes"
537 When you create a default stream with bt_stream_create()
538 or bt_stream_create_with_id(), the stream's initial user
539 attributes is an empty \bt_map_val.
542 Stream from which to borrow the user attributes.
545 User attributes of \bt_p{stream} (a \bt_map_val).
547 @bt_pre_not_null{stream}
549 @sa bt_stream_set_user_attributes() —
550 Sets the user attributes of a stream.
551 @sa bt_stream_borrow_user_attributes_const() —
552 \c const version of this function.
554 extern bt_value
*bt_stream_borrow_user_attributes(bt_stream
*stream
);
558 Borrows the user attributes of the stream \bt_p{stream}
561 See bt_stream_borrow_user_attributes().
563 extern const bt_value
*bt_stream_borrow_user_attributes_const(
564 const bt_stream
*stream
);
569 @name Reference count
575 Increments the \ref api-fund-shared-object "reference count" of
576 the stream \bt_p{stream}.
580 Stream of which to increment the reference count.
585 @sa bt_stream_put_ref() —
586 Decrements the reference count of a stream.
588 extern void bt_stream_get_ref(const bt_stream
*stream
);
592 Decrements the \ref api-fund-shared-object "reference count" of
593 the stream \bt_p{stream}.
597 Stream of which to decrement the reference count.
602 @sa bt_stream_get_ref() —
603 Increments the reference count of a stream.
605 extern void bt_stream_put_ref(const bt_stream
*stream
);
609 Decrements the reference count of the stream
610 \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
614 Stream of which to decrement the reference count.
619 @bt_pre_assign_expr{_stream}
621 #define BT_STREAM_PUT_REF_AND_RESET(_stream) \
623 bt_stream_put_ref(_stream); \
629 Decrements the reference count of the stream \bt_p{_dst}, sets
630 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
632 This macro effectively moves a stream reference from the expression
633 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
634 \bt_p{_dst} reference.
638 Destination expression.
649 @bt_pre_assign_expr{_dst}
650 @bt_pre_assign_expr{_src}
652 #define BT_STREAM_MOVE_REF(_dst, _src) \
654 bt_stream_put_ref(_dst); \
667 #endif /* BABELTRACE2_TRACE_IR_STREAM_H */