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