Move to kernel style SPDX license identifiers
[babeltrace.git] / include / babeltrace2 / trace-ir / stream.h
CommitLineData
c057dea0 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
c057dea0 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
c057dea0
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_TRACE_IR_STREAM_H
8#define BABELTRACE2_TRACE_IR_STREAM_H
9
4fa90f32
PP
10#ifndef __BT_IN_BABELTRACE_H
11# error "Please include <babeltrace2/babeltrace.h> instead."
12#endif
13
d24d5663
PP
14#include <stdint.h>
15
3fadfbc0 16#include <babeltrace2/types.h>
b19ff26f 17
c057dea0
PP
18#ifdef __cplusplus
19extern "C" {
20#endif
21
43c59509
PP
22/*!
23@defgroup api-tir-stream Stream
24@ingroup api-tir
25
26@brief
27 Trace stream.
28
29A <strong><em>stream</em></strong> is a conceptual
30\ref api-msg-seq "sequence of messages" within a \bt_trace:
31
32@image html trace-structure.png
33
34In the illustration above, notice that:
35
36- A \bt_stream is a conceptual sequence of \bt_p_msg.
37
38 The sequence always starts with a \bt_sb_msg and ends with a
39 \bt_se_msg.
40
41- A stream is an instance of a \bt_stream_cls.
42
43- A \bt_trace contains one or more streams.
44
45A stream is a \ref api-tir "trace IR" data object.
46
47A stream is said to be a \em conceptual sequence of messages because the
48stream object itself does not contain messages: it only represents a
49common timeline to which messages are associated.
50
51\bt_cp_comp exchange messages, within a trace processing \bt_graph,
52which can belong to different streams, as long as the stream clocks are
53\ref api-tir-clock-cls-origin "correlatable".
54
55A typical use case for streams is to use one for each traced CPU. Then
118ae153 56the messages related to a given stream are the ones which occurred on a
43c59509
PP
57given CPU. Other schemes are possible: they are completely
58application-specific, and \bt_name does not enforce any specific
59stream arrangement pattern.
60
61A \bt_trace contains streams. All the streams of a
62given trace, for a given stream class, have unique numeric IDs. Borrow
63the trace which contains a stream with bt_stream_borrow_trace() or
64bt_stream_borrow_trace_const().
65
66A \bt_stream can conceptually contain a default clock if its class
67has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
68There's no function to access a stream's default clock because it's
69a stateful object: \bt_p_msg cannot refer to stateful objects
70because 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
73stream's default clock (a \bt_clock_cls instance):
74
75@image html clocks.png
76
77In the illustration above, notice that:
78
79- Streams (horizontal blue rectangles) are instances of a
80 \bt_stream_cls (orange).
81
82- A stream class has a default \bt_clock_cls (orange bell alarm clock).
83
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.
86
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.
90
91 In other words, a default clock snapshot contains the value of the
118ae153 92 stream's default clock when this message occurred.
43c59509
PP
93
94To create a stream:
95
96<dl>
97 <dt>
98 If bt_stream_class_assigns_automatic_stream_id() returns
99 #BT_TRUE (the default) for the stream class to use
100 </dt>
101 <dd>Use bt_stream_create().</dd>
102
103 <dt>
104 If bt_stream_class_assigns_automatic_stream_id() returns
105 #BT_FALSE for the stream class to use
106 </dt>
107 <dd>Use bt_stream_create_with_id().</dd>
108</dl>
109
110A stream is a \ref api-fund-shared-object "shared object": get a
111new reference with bt_stream_get_ref() and put an existing
112reference with bt_stream_put_ref().
113
114Some library functions \ref api-fund-freezing "freeze" streams on
115success. The documentation of those functions indicate this
116postcondition.
117
118The type of a stream is #bt_stream.
119
120<h1>Properties</h1>
121
122A stream has the following property:
123
124<dl>
125 <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
126 <dd>
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.
131
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().
137
138 You cannot change the numeric ID once the stream is created.
139
140 Get a stream's numeric ID with bt_stream_get_id().
141 </dd>
142
143 <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
144 <dd>
145 Name of the stream.
146
147 Use bt_stream_set_name() and bt_stream_get_name().
148 </dd>
149
150 <dt>
151 \anchor api-tir-stream-prop-user-attrs
152 \bt_dt_opt User attributes
153 </dt>
154 <dd>
155 User attributes of the stream.
156
157 User attributes are custom attributes attached to a stream.
158
159 Use bt_stream_set_user_attributes(),
160 bt_stream_borrow_user_attributes(), and
161 bt_stream_borrow_user_attributes_const().
162 </dd>
163</dl>
164*/
165
166/*! @{ */
167
168/*!
169@name Type
170@{
171
172@typedef struct bt_stream bt_stream;
173
174@brief
175 Stream.
176
177@}
178*/
179
180/*!
181@name Creation
182@{
183*/
184
185/*!
186@brief
187 Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
188 adds it to the \bt_trace \bt_p{trace}.
189
190This function instantiates \bt_p{stream_class}.
191
192@attention
193 @parblock
194 Only use this function if
195
196 @code
197 bt_stream_class_assigns_automatic_stream_id(stream_class)
198 @endcode
199
200 returns #BT_TRUE.
201
202 Otherwise, use bt_stream_create_with_id().
203 @endparblock
204
205On success, the returned stream has the following property values:
206
207<table>
208 <tr>
209 <th>Property
210 <th>Value
211 <tr>
212 <td>\ref api-tir-stream-prop-id "Numeric ID"
213 <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
214 <tr>
215 <td>\ref api-tir-stream-prop-name "Name"
216 <td>\em None
217 <tr>
218 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
219 <td>Empty \bt_map_val
220</table>
221
222@param[in] stream_class
223 Stream class from which to create the stream.
224@param[in] trace
225 Trace to add the created stream to.
226
227@returns
228 New stream reference, or \c NULL on memory error.
229
230@bt_pre_not_null{stream_class}
231@pre
232 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
233 returns #BT_TRUE.
234@bt_pre_not_null{trace}
235
236@bt_post_success_frozen{stream_class}
237@bt_post_success_frozen{trace}
238
239@sa bt_stream_create_with_id() &mdash;
240 Creates a stream with a specific numeric ID and adds it to a
241 trace.
242*/
b19ff26f
PP
243extern bt_stream *bt_stream_create(bt_stream_class *stream_class,
244 bt_trace *trace);
40f4ba76 245
43c59509
PP
246/*!
247@brief
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}.
251
252This function instantiates \bt_p{stream_class}.
253
254@attention
255 @parblock
256 Only use this function if
257
258 @code
259 bt_stream_class_assigns_automatic_stream_id(stream_class)
260 @endcode
261
262 returns #BT_FALSE.
263
264 Otherwise, use bt_stream_create().
265 @endparblock
266
267On success, the returned stream has the following property values:
268
269<table>
270 <tr>
271 <th>Property
272 <th>Value
273 <tr>
274 <td>\ref api-tir-stream-prop-id "Numeric ID"
275 <td>\bt_p{id}
276 <tr>
277 <td>\ref api-tir-stream-prop-name "Name"
278 <td>\em None
279 <tr>
280 <td>\ref api-tir-stream-prop-user-attrs "User attributes"
281 <td>Empty \bt_map_val
282</table>
283
284@param[in] stream_class
285 Stream class from which to create the stream.
286@param[in] trace
287 Trace to add the created stream to.
288@param[in] id
289 Numeric ID of the stream to create and add to \bt_p{trace}.
290
291@returns
292 New stream reference, or \c NULL on memory error.
293
294@bt_pre_not_null{stream_class}
295@pre
296 <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
297 returns #BT_FALSE.
298@bt_pre_not_null{trace}
299@pre
300 \bt_p{trace} does not contain an instance of \bt_p{stream_class}
301 with the numeric ID \bt_p{id}.
302
303@bt_post_success_frozen{stream_class}
304@bt_post_success_frozen{trace}
305
306@sa bt_stream_create() &mdash;
307 Creates a stream with an automatic numeric ID and adds it to a
308 trace.
309*/
b19ff26f
PP
310extern bt_stream *bt_stream_create_with_id(
311 bt_stream_class *stream_class,
312 bt_trace *trace, uint64_t id);
862ca4ed 313
43c59509 314/*! @} */
c6962c96 315
43c59509
PP
316/*!
317@name Class access
318@{
319*/
c6962c96 320
43c59509
PP
321/*!
322@brief
323 Borrows the \ref api-tir-stream-cls "class" of the stream
324 \bt_p{stream}.
325
326@param[in] stream
327 Stream of which to borrow the class.
328
329@returns
330 \em Borrowed reference of the class of \bt_p{stream}.
331
332@bt_pre_not_null{stream}
44c440bc 333
43c59509
PP
334@sa bt_stream_borrow_class_const() &mdash;
335 \c const version of this function.
336*/
b19ff26f 337extern bt_stream_class *bt_stream_borrow_class(bt_stream *stream);
094ff7c0 338
43c59509
PP
339/*!
340@brief
341 Borrows the \ref api-tir-stream-cls "class" of the stream
342 \bt_p{stream} (\c const version).
343
344See bt_stream_borrow_class().
345*/
346extern const bt_stream_class *bt_stream_borrow_class_const(
347 const bt_stream *stream);
348
349/*! @} */
350
351/*!
352@name Trace access
353@{
354*/
355
356/*!
357@brief
358 Borrows the \bt_trace which contains the stream \bt_p{stream}.
359
360@param[in] stream
361 Stream of which to borrow the trace containing it.
362
363@returns
364 \em Borrowed reference of the trace containing \bt_p{stream}.
365
366@bt_pre_not_null{stream}
367
368@sa bt_stream_borrow_trace_const() &mdash;
369 \c const version of this function.
370*/
371extern bt_trace *bt_stream_borrow_trace(bt_stream *stream);
372
373/*!
374@brief
375 Borrows the \bt_trace which contains the stream \bt_p{stream}
376 (\c const version).
377
378See bt_stream_borrow_trace().
379*/
380extern const bt_trace *bt_stream_borrow_trace_const(
381 const bt_stream *stream);
382
383/*! @} */
384
385/*!
386@name Properties
387@{
388*/
389
390/*!
391@brief
392 Returns the numeric ID of the stream \bt_p{stream}.
393
394See the \ref api-tir-stream-prop-id "numeric ID" property.
395
396@param[in] stream
397 Stream of which to get the numeric ID.
398
399@returns
400 Numeric ID of \bt_p{stream}.
401
402@bt_pre_not_null{stream}
403
404@sa bt_stream_create_with_id() &mdash;
405 Creates a stream with a specific numeric ID and adds it to a
406 trace.
407*/
408extern uint64_t bt_stream_get_id(const bt_stream *stream);
409
410/*!
411@brief
412 Status codes for bt_stream_set_name().
413*/
d24d5663 414typedef enum bt_stream_set_name_status {
43c59509
PP
415 /*!
416 @brief
417 Success.
418 */
d24d5663 419 BT_STREAM_SET_NAME_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
420
421 /*!
422 @brief
423 Out of memory.
424 */
425 BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
d24d5663
PP
426} bt_stream_set_name_status;
427
43c59509
PP
428/*!
429@brief
430 Sets the name of the stream \bt_p{stream} to
431 a copy of \bt_p{name}.
432
433See the \ref api-tir-stream-prop-name "name" property.
434
435@param[in] stream
436 Stream of which to set the name to \bt_p{name}.
437@param[in] name
438 New name of \bt_p{stream} (copied).
439
440@retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
441 Success.
442@retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
443 Out of memory.
444
445@bt_pre_not_null{stream}
446@bt_pre_hot{stream}
447@bt_pre_not_null{name}
448
449@sa bt_stream_get_name() &mdash;
450 Returns the name of a stream.
451*/
d24d5663 452extern bt_stream_set_name_status bt_stream_set_name(bt_stream *stream,
3dcff82b 453 const char *name);
c057dea0 454
43c59509
PP
455/*!
456@brief
457 Returns the name of the stream \bt_p{stream}.
458
459See the \ref api-tir-stream-prop-name "name" property.
460
461If \bt_p{stream} has no name, this function returns \c NULL.
462
463@param[in] stream
464 Stream of which to get the name.
465
466@returns
467 @parblock
468 Name of \bt_p{stream}, or \c NULL if none.
469
470 The returned pointer remains valid as long as \bt_p{stream}
471 is not modified.
472 @endparblock
473
474@bt_pre_not_null{stream}
475
476@sa bt_stream_class_set_name() &mdash;
477 Sets the name of a stream.
478*/
479extern const char *bt_stream_get_name(const bt_stream *stream);
480
481/*!
482@brief
483 Sets the user attributes of the stream \bt_p{stream} to
484 \bt_p{user_attributes}.
485
486See the \ref api-tir-stream-prop-user-attrs "user attributes"
487property.
488
489@note
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.
495
496@param[in] stream
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}.
501
502@bt_pre_not_null{stream}
503@bt_pre_hot{stream}
504@bt_pre_not_null{user_attributes}
505@bt_pre_is_map_val{user_attributes}
506
507@sa bt_stream_borrow_user_attributes() &mdash;
508 Borrows the user attributes of a stream.
509*/
510extern void bt_stream_set_user_attributes(
511 bt_stream *stream, const bt_value *user_attributes);
512
513/*!
514@brief
515 Borrows the user attributes of the stream \bt_p{stream}.
516
517See the \ref api-tir-stream-prop-user-attrs "user attributes"
518property.
519
520@note
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.
524
525@param[in] stream
526 Stream from which to borrow the user attributes.
527
528@returns
529 User attributes of \bt_p{stream} (a \bt_map_val).
530
531@bt_pre_not_null{stream}
532
533@sa bt_stream_set_user_attributes() &mdash;
534 Sets the user attributes of a stream.
535@sa bt_stream_borrow_user_attributes_const() &mdash;
536 \c const version of this function.
537*/
538extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream);
539
540/*!
541@brief
542 Borrows the user attributes of the stream \bt_p{stream}
543 (\c const version).
544
545See bt_stream_borrow_user_attributes().
546*/
547extern const bt_value *bt_stream_borrow_user_attributes_const(
548 const bt_stream *stream);
549
550/*! @} */
551
552/*!
553@name Reference count
554@{
555*/
556
557/*!
558@brief
559 Increments the \ref api-fund-shared-object "reference count" of
560 the stream \bt_p{stream}.
561
562@param[in] stream
563 @parblock
564 Stream of which to increment the reference count.
565
566 Can be \c NULL.
567 @endparblock
568
569@sa bt_stream_put_ref() &mdash;
570 Decrements the reference count of a stream.
571*/
572extern void bt_stream_get_ref(const bt_stream *stream);
573
574/*!
575@brief
576 Decrements the \ref api-fund-shared-object "reference count" of
577 the stream \bt_p{stream}.
578
579@param[in] stream
580 @parblock
581 Stream of which to decrement the reference count.
582
583 Can be \c NULL.
584 @endparblock
585
586@sa bt_stream_get_ref() &mdash;
587 Increments the reference count of a stream.
588*/
589extern void bt_stream_put_ref(const bt_stream *stream);
590
591/*!
592@brief
593 Decrements the reference count of the stream
594 \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
595
596@param _stream
597 @parblock
598 Stream of which to decrement the reference count.
599
600 Can contain \c NULL.
601 @endparblock
602
603@bt_pre_assign_expr{_stream}
604*/
605#define BT_STREAM_PUT_REF_AND_RESET(_stream) \
606 do { \
607 bt_stream_put_ref(_stream); \
608 (_stream) = NULL; \
609 } while (0)
610
611/*!
612@brief
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.
615
616This 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.
619
620@param _dst
621 @parblock
622 Destination expression.
623
624 Can contain \c NULL.
625 @endparblock
626@param _src
627 @parblock
628 Source expression.
629
630 Can contain \c NULL.
631 @endparblock
632
633@bt_pre_assign_expr{_dst}
634@bt_pre_assign_expr{_src}
635*/
636#define BT_STREAM_MOVE_REF(_dst, _src) \
637 do { \
638 bt_stream_put_ref(_dst); \
639 (_dst) = (_src); \
640 (_src) = NULL; \
641 } while (0)
642
643/*! @} */
644
645/*! @} */
646
c057dea0
PP
647#ifdef __cplusplus
648}
649#endif
650
924dc299 651#endif /* BABELTRACE2_TRACE_IR_STREAM_H */
This page took 0.084404 seconds and 4 git commands to generate.