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