1 #ifndef BABELTRACE2_TRACE_IR_STREAM_CLASS_H
2 #define BABELTRACE2_TRACE_IR_STREAM_CLASS_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-cls Stream class
43 Class of \bt_p_stream.
45 A <strong><em>stream class</em></strong> is the class of \bt_p_stream:
47 @image html trace-structure.png
49 In the illustration above, notice that:
51 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages".
53 The sequence always starts with a \bt_sb_msg and ends with a
56 - A stream is an instance of a stream class.
58 A stream class is a \ref api-tir "trace IR" metadata object.
60 A stream class is a \ref api-fund-shared-object "shared object": get a
61 new reference with bt_stream_class_get_ref() and put an existing
62 reference with bt_stream_class_put_ref().
64 Some library functions \ref api-fund-freezing "freeze" stream classes on
65 success. The documentation of those functions indicate this
66 postcondition. You can still create and add an \bt_p_ev_cls to a frozen
67 stream class with bt_event_class_create() or
68 bt_event_class_create_with_id().
70 The type of a stream class is #bt_stream_class.
72 A \bt_trace_cls contains stream classes. All the stream classes of a
73 given trace class have unique
74 \ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class
75 which contains a stream class with bt_stream_class_borrow_trace_class()
76 or bt_stream_class_borrow_trace_class_const().
78 A stream class contains \bt_p_ev_cls. All the event classes of a given
79 stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get
80 the number of event classes in a stream class with
81 bt_stream_class_get_event_class_count(). Borrow a specific event class
82 from a stream class with bt_stream_class_borrow_event_class_by_index(),
83 bt_stream_class_borrow_event_class_by_index_const(),
84 bt_stream_class_borrow_event_class_by_id(), and
85 bt_stream_class_borrow_event_class_by_id_const().
87 A stream class controls what its instances (\bt_p_stream) support:
90 <dt>Default clock</dt>
92 By default, a stream class's streams do not have default clocks.
94 Set the default \bt_clock_cls of a stream class with
95 bt_stream_class_set_default_clock_class(). This makes all its
96 streams have their own default clock.
99 <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt>
101 By default, a stream class's streams do not support \bt_p_pkt.
103 In other words, you cannot create a packet for such a stream,
104 therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this
107 Enable packet support for a stream class's streams with
108 bt_stream_class_set_supports_packets().
110 bt_stream_class_set_supports_packets() also configures whether or
111 not the packets of the stream class's instances have beginning
112 and/or end default \bt_p_cs.
115 <dt>Discarded events</dt>
117 By default, a stream class's streams do not support discarded
120 In other words, you cannot create \bt_p_disc_ev_msg for such a
123 Enable discarded events support for a stream class's streams with
124 bt_stream_class_set_supports_discarded_events().
126 bt_stream_class_set_supports_discarded_events() also configures
127 whether or not the discarded events messages of the stream class's
128 instances have beginning and end default \bt_p_cs to indicate the
129 discarded events time range.
132 <dt>Discarded packets</dt>
134 By default, a stream class's streams do not support discarded
137 In other words, you cannot create \bt_p_disc_pkt_msg for such a
140 Enable discarded packets support for a stream class's streams with
141 bt_stream_class_set_supports_discarded_packets(). This also implies
142 that you must enable packet support with
143 bt_stream_class_set_supports_packets().
145 bt_stream_class_set_supports_discarded_packets() also configures
146 whether or not the discarded packets messages of the stream class's
147 instances have beginning and end \bt_p_cs to indicate the
148 discarded packets time range.
152 Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a
153 stream class get automatic numeric IDs with
154 bt_stream_class_set_assigns_automatic_event_class_id() and
155 bt_stream_class_set_assigns_automatic_stream_id().
157 To create a default stream class:
161 If bt_trace_class_assigns_automatic_stream_class_id() returns
162 #BT_TRUE (the default) for the trace class to use
164 <dd>Use bt_stream_class_create().</dd>
167 If bt_trace_class_assigns_automatic_stream_class_id() returns
168 #BT_FALSE for the trace class to use
170 <dd>Use bt_stream_class_create_with_id().</dd>
175 A stream class has the following properties:
178 <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt>
180 Numeric ID, unique amongst the numeric IDs of the stream class's
181 \bt_trace_cls's stream classes.
183 Depending on whether or not the stream class's trace class
184 automatically assigns \bt_ev_cls IDs
185 (see bt_trace_class_assigns_automatic_stream_class_id()),
186 set the stream class's numeric ID on creation with
187 bt_stream_class_create() or bt_stream_class_create_with_id().
189 You cannot change the numeric ID once the stream class is created.
191 Get a stream class's numeric ID with bt_stream_class_get_id().
194 <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
196 Name of the stream class.
198 Use bt_stream_class_set_name() and bt_stream_class_get_name().
202 \anchor api-tir-stream-cls-prop-def-clock-cls
203 \bt_dt_opt Default clock class
206 Default \bt_clock_cls of the stream class.
208 As of \bt_name_version_min_maj, a stream class either has a default
209 clock class or none: it cannot have more than one clock class.
211 When a stream class has a default clock class, then all its
212 instances (\bt_p_stream) have a default clock which is an instance
213 of the stream class's default clock class.
215 Use bt_stream_class_set_default_clock_class(),
216 bt_stream_class_borrow_default_clock_class(), and
217 bt_stream_class_borrow_default_clock_class_const().
221 \anchor api-tir-stream-cls-prop-pc-fc
222 \bt_dt_opt Packet context field class
225 \bt_c_pkt context \bt_fc of the stream class.
227 This property is only relevant if the stream class
228 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
230 The context of a \bt_pkt contains data which is common to all the
233 Use bt_stream_class_set_packet_context_field_class()
234 bt_stream_class_borrow_packet_context_field_class(),
235 and bt_stream_class_borrow_packet_context_field_class_const().
239 \anchor api-tir-stream-cls-prop-ecc-fc
240 \bt_dt_opt Event common context field class
243 \bt_c_ev common context \bt_fc of the stream class.
245 The common context of an \bt_ev contains contextual data of which
246 the layout is common to all the stream class's \bt_p_ev_cls.
248 Use bt_stream_class_set_event_common_context_field_class()
249 bt_stream_class_borrow_event_common_context_field_class(),
250 and bt_stream_class_borrow_event_common_context_field_class_const().
254 \anchor api-tir-stream-cls-prop-auto-ec-id
255 Assigns automatic event class IDs?
258 Whether or not the \bt_p_ev_cls you create and add to the stream
259 class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically.
261 Depending on the value of this property, to create an event class
262 and add it to the stream class:
267 Use bt_event_class_create().
272 Use bt_event_class_create_with_id().
276 Use bt_stream_class_set_assigns_automatic_event_class_id()
277 and bt_stream_class_assigns_automatic_event_class_id().
281 \anchor api-tir-stream-cls-prop-auto-stream-id
282 Assigns automatic stream IDs?
285 Whether or not the streams you create from the stream class
286 get \ref api-tir-stream-prop-id "numeric IDs" automatically.
288 Depending on the value of this property, to create a stream
289 from the stream class:
294 Use bt_stream_create().
299 Use bt_stream_create_with_id().
303 Use bt_stream_class_set_assigns_automatic_stream_id()
304 and bt_stream_class_assigns_automatic_stream_id().
308 \anchor api-tir-stream-cls-prop-supports-pkt
312 Whether or not the streams you create from the stream class
315 If a stream has packets, then all the stream's \bt_p_ev are
316 conceptually contained within packets, which means you must
317 create \bt_p_ev_msg for such streams with
318 bt_message_event_create_with_packet() or
319 bt_message_event_create_with_packet_and_default_clock_snapshot()
320 instead of bt_message_event_create() or
321 bt_message_event_create_with_default_clock_snapshot().
323 It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to
324 indicate where packets begin and end within the stream's
325 \ref api-msg-seq "message sequence".
327 Use bt_stream_class_set_supports_packets() and
328 bt_stream_class_supports_packets().
332 \anchor api-tir-stream-cls-prop-pkt-beg-cs
333 Packets have a beginning default clock snapshot?
336 Whether or not the \bt_p_pkt of the streams you create from the
337 stream class have beginning default \bt_p_cs.
339 This property is only relevant if the stream class
340 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
342 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
344 If the stream packets have a beginning default clock snapshot, then
345 you must create \bt_p_pb_msg with
346 bt_message_packet_beginning_create_with_default_clock_snapshot()
347 instead of bt_message_packet_beginning_create().
349 Use bt_stream_class_set_supports_packets() and
350 bt_stream_class_packets_have_beginning_default_clock_snapshot().
354 \anchor api-tir-stream-cls-prop-pkt-end-cs
355 Packets have an end default clock snapshot?
358 Whether or not the \bt_p_pkt of the streams you create from the
359 stream class have end default \bt_p_cs.
361 This property is only relevant if the stream class
362 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
364 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
366 If the stream packets have an end default clock snapshot, then you
367 must create \bt_p_pe_msg with
368 bt_message_packet_end_create_with_default_clock_snapshot() instead
369 of bt_message_packet_end_create().
371 Use bt_stream_class_set_supports_packets() and
372 bt_stream_class_packets_have_end_default_clock_snapshot().
376 \anchor api-tir-stream-cls-prop-supports-disc-ev
377 Supports discarded events?
380 Whether or not the streams you create from the stream class can have
383 If the stream class supports discarded events, then you can create
384 \bt_p_disc_ev_msg for this stream.
386 Use bt_stream_class_set_supports_discarded_events()
387 and bt_stream_class_supports_discarded_events().
391 \anchor api-tir-stream-cls-prop-disc-ev-cs
392 Discarded events have default clock snapshots?
395 Whether or not the stream's \bt_p_disc_ev_msg have
396 default beginning and end \bt_p_cs to indicate the discarded events
399 This property is only relevant if the stream class
400 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events"
402 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
404 If the stream's discarded events messages have beginning and end
405 default clock snapshots, then you must create them with
406 bt_message_discarded_events_create_with_default_clock_snapshots()
407 instead of bt_message_discarded_events_create().
409 Use bt_stream_class_set_supports_discarded_events()
410 and bt_stream_class_discarded_events_have_default_clock_snapshots().
414 \anchor api-tir-stream-cls-prop-supports-disc-pkt
415 Supports discarded packets?
418 Whether or not the streams you create from the stream class can have
421 This property is only relevant if the stream class
422 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
424 If the stream class supports discarded packets, then you can create
425 \bt_p_disc_pkt_msg for this stream.
427 Use bt_stream_class_set_supports_discarded_packets()
428 and bt_stream_class_supports_discarded_packets().
432 \anchor api-tir-stream-cls-prop-disc-pkt-cs
433 Discarded packets have default clock snapshots?
436 Whether or not the stream's \bt_p_disc_pkt_msg have
437 default beginning and end \bt_p_cs to indicate the discarded
440 This property is only relevant if the stream class
441 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets"
443 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
445 If the stream's discarded packets messages have default clock
446 snapshots, then you must create them with
447 bt_message_discarded_packets_create_with_default_clock_snapshots()
448 instead of bt_message_discarded_packets_create().
450 Use bt_stream_class_set_supports_discarded_packets()
451 and bt_stream_class_discarded_packets_have_default_clock_snapshots().
455 \anchor api-tir-stream-cls-prop-user-attrs
456 \bt_dt_opt User attributes
459 User attributes of the stream class.
461 User attributes are custom attributes attached to a stream class.
463 Use bt_stream_class_set_user_attributes(),
464 bt_stream_class_borrow_user_attributes(), and
465 bt_stream_class_borrow_user_attributes_const().
476 @typedef struct bt_stream_class bt_stream_class;
491 Creates a default stream class and adds it to the \bt_trace_cls
496 Only use this function if
499 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
504 Otherwise, use bt_stream_class_create_with_id().
507 On success, the returned stream class has the following property values:
514 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
515 <td>Automatically assigned by \bt_p{trace_class}
517 <td>\ref api-tir-stream-cls-prop-name "Name"
520 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
523 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
526 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
529 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
532 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
535 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
538 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
541 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
544 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
547 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
550 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
553 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
556 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
557 <td>Empty \bt_map_val
560 @param[in] trace_class
561 Trace class to add the created stream class to.
564 New stream class reference, or \c NULL on memory error.
566 @bt_pre_not_null{trace_class}
568 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
571 @bt_post_success_frozen{trace_class}
573 @sa bt_stream_class_create_with_id() —
574 Creates a stream class with a specific numeric ID and adds it to a
577 extern bt_stream_class
*bt_stream_class_create(
578 bt_trace_class
*trace_class
);
582 Creates a default stream class with the numeric ID \bt_p{id} and adds
583 it to the \bt_trace_cls \bt_p{trace_class}.
587 Only use this function if
590 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
595 Otherwise, use bt_stream_class_create().
598 On success, the returned stream class has the following property values:
605 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
608 <td>\ref api-tir-stream-cls-prop-name "Name"
611 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
614 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
617 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
620 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
623 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
626 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
629 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
632 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
635 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
638 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
641 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
644 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
647 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
648 <td>Empty \bt_map_val
651 @param[in] trace_class
652 Trace class to add the created stream class to.
654 Numeric ID of the stream class to create and add to
658 New stream class reference, or \c NULL on memory error.
660 @bt_pre_not_null{trace_class}
662 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
665 \bt_p{trace_class} does not contain a stream class with the numeric
668 @bt_post_success_frozen{trace_class}
670 @sa bt_stream_class_create() —
671 Creates a stream class with an automatic numeric ID and adds it to a
674 extern bt_stream_class
*bt_stream_class_create_with_id(
675 bt_trace_class
*trace_class
, uint64_t id
);
680 @name Trace class access
686 Borrows the \bt_trace_cls which contains the stream class
689 @param[in] stream_class
690 Stream class from which to borrow the trace class which contains it.
693 Trace class which contains \bt_p{stream_class}.
695 @bt_pre_not_null{stream_class}
697 @sa bt_stream_class_borrow_trace_class_const() —
698 \c const version of this function.
700 extern bt_trace_class
*bt_stream_class_borrow_trace_class(
701 bt_stream_class
*stream_class
);
705 Borrows the \bt_trace_cls which contains the stream class
706 \bt_p{stream_class} (\c const version).
708 See bt_stream_class_borrow_trace_class().
710 extern const bt_trace_class
*bt_stream_class_borrow_trace_class_const(
711 const bt_stream_class
*stream_class
);
716 @name Event class access
722 Returns the number of \bt_p_ev_cls contained in the stream
723 class \bt_p{stream_class}.
725 @param[in] stream_class
726 Stream class of which to get the number of contained event classes.
729 Number of contained event classes in \bt_p{stream_class}.
731 @bt_pre_not_null{stream_class}
733 extern uint64_t bt_stream_class_get_event_class_count(
734 const bt_stream_class
*stream_class
);
738 Borrows the \bt_ev_cls at index \bt_p{index} from the
739 stream class \bt_p{stream_class}.
741 @param[in] stream_class
742 Stream class from which to borrow the event class at index
745 Index of the event class to borrow from \bt_p{stream_class}.
749 \em Borrowed reference of the event class of
750 \bt_p{stream_class} at index \bt_p{index}.
752 The returned pointer remains valid as long as \bt_p{stream_class}
756 @bt_pre_not_null{stream_class}
758 \bt_p{index} is less than the number of event classes in
759 \bt_p{stream_class} (as returned by
760 bt_stream_class_get_event_class_count()).
762 @sa bt_stream_class_get_event_class_count() —
763 Returns the number of event classes contained in a stream class.
764 @sa bt_stream_class_borrow_event_class_by_index_const() —
765 \c const version of this function.
767 extern bt_event_class
*
768 bt_stream_class_borrow_event_class_by_index(
769 bt_stream_class
*stream_class
, uint64_t index
);
773 Borrows the \bt_ev_cls at index \bt_p{index} from the
774 stream class \bt_p{stream_class} (\c const version).
776 See bt_stream_class_borrow_event_class_by_index().
778 extern const bt_event_class
*
779 bt_stream_class_borrow_event_class_by_index_const(
780 const bt_stream_class
*stream_class
, uint64_t index
);
784 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
785 stream class \bt_p{stream_class}.
787 If there's no event class having the numeric ID \bt_p{id} in
788 \bt_p{stream_class}, this function returns \c NULL.
790 @param[in] stream_class
791 Stream class from which to borrow the event class having the
792 numeric ID \bt_p{id}.
794 ID of the event class to borrow from \bt_p{stream_class}.
798 \em Borrowed reference of the event class of
799 \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL
802 The returned pointer remains valid as long as \bt_p{stream_class}
806 @bt_pre_not_null{stream_class}
808 @sa bt_stream_class_borrow_event_class_by_id_const() —
809 \c const version of this function.
811 extern bt_event_class
*
812 bt_stream_class_borrow_event_class_by_id(
813 bt_stream_class
*stream_class
, uint64_t id
);
817 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
818 stream class \bt_p{stream_class} (\c const version).
820 See bt_stream_class_borrow_event_class_by_id().
822 extern const bt_event_class
*
823 bt_stream_class_borrow_event_class_by_id_const(
824 const bt_stream_class
*stream_class
, uint64_t id
);
835 Returns the numeric ID of the stream class \bt_p{stream_class}.
837 See the \ref api-tir-stream-cls-prop-id "numeric ID" property.
839 @param[in] stream_class
840 Stream class of which to get the numeric ID.
843 Numeric ID of \bt_p{stream_class}.
845 @bt_pre_not_null{stream_class}
847 @sa bt_stream_class_create_with_id() —
848 Creates a stream class with a specific numeric ID and adds it to a
851 extern uint64_t bt_stream_class_get_id(
852 const bt_stream_class
*stream_class
);
856 Status codes for bt_stream_class_set_name().
858 typedef enum bt_stream_class_set_name_status
{
863 BT_STREAM_CLASS_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
869 BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
870 } bt_stream_class_set_name_status
;
874 Sets the name of the stream class \bt_p{stream_class} to
875 a copy of \bt_p{name}.
877 See the \ref api-tir-stream-cls-prop-name "name" property.
879 @param[in] stream_class
880 Stream class of which to set the name to \bt_p{name}.
882 New name of \bt_p{stream_class} (copied).
884 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
886 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
889 @bt_pre_not_null{stream_class}
890 @bt_pre_hot{stream_class}
891 @bt_pre_not_null{name}
893 @sa bt_stream_class_get_name() —
894 Returns the name of a stream class.
896 extern bt_stream_class_set_name_status
bt_stream_class_set_name(
897 bt_stream_class
*stream_class
, const char *name
);
901 Returns the name of the stream class \bt_p{stream_class}.
903 See the \ref api-tir-stream-cls-prop-name "name" property.
905 If \bt_p{stream_class} has no name, this function returns \c NULL.
907 @param[in] stream_class
908 Stream class of which to get the name.
912 Name of \bt_p{stream_class}, or \c NULL if none.
914 The returned pointer remains valid as long as \bt_p{stream_class}
918 @bt_pre_not_null{stream_class}
920 @sa bt_stream_class_set_name() —
921 Sets the name of a stream class.
923 extern const char *bt_stream_class_get_name(
924 const bt_stream_class
*stream_class
);
928 Status codes for bt_stream_class_set_default_clock_class().
930 typedef enum bt_stream_class_set_default_clock_class_status
{
935 BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
936 } bt_stream_class_set_default_clock_class_status
;
940 Sets the default \bt_clock_cls of the stream class
941 \bt_p{stream_class} to \bt_p{clock_class}.
943 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
946 @param[in] stream_class
947 Stream class of which to set the default clock class to
949 @param[in] clock_class
950 New default clock class of \bt_p{stream_class}.
952 @retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
955 @bt_pre_not_null{stream_class}
956 @bt_pre_hot{stream_class}
957 @bt_pre_not_null{clock_class}
959 @sa bt_stream_class_borrow_default_clock_class() —
960 Borrows the default clock class of a stream class.
961 @sa bt_stream_class_borrow_default_clock_class_const() —
962 Borrows the default clock class of a stream class (\c const version).
964 extern bt_stream_class_set_default_clock_class_status
965 bt_stream_class_set_default_clock_class(
966 bt_stream_class
*stream_class
,
967 bt_clock_class
*clock_class
);
971 Borrows the default \bt_clock_cls from the stream class
974 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
977 If \bt_p{stream_class} has no default clock class, this function
980 @param[in] stream_class
981 Stream class from which to borrow the default clock class.
984 \em Borrowed reference of the default clock class of
985 \bt_p{stream_class}, or \c NULL if none.
987 @bt_pre_not_null{stream_class}
989 @sa bt_stream_class_set_default_clock_class() —
990 Sets the default clock class of a stream class.
991 @sa bt_stream_class_borrow_default_clock_class_const() —
992 \c const version of this function.
994 extern bt_clock_class
*bt_stream_class_borrow_default_clock_class(
995 bt_stream_class
*stream_class
);
999 Borrows the default \bt_clock_cls from the stream class
1000 \bt_p{stream_class} (\c const version).
1002 See bt_stream_class_borrow_default_clock_class().
1004 extern const bt_clock_class
*
1005 bt_stream_class_borrow_default_clock_class_const(
1006 const bt_stream_class
*stream_class
);
1010 Status codes for bt_stream_class_set_packet_context_field_class()
1011 and bt_stream_class_set_event_common_context_field_class().
1013 typedef enum bt_stream_class_set_field_class_status
{
1018 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1024 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1025 } bt_stream_class_set_field_class_status
;
1029 Sets the packet context \bt_fc of the stream class
1030 \bt_p{stream_class} to \bt_p{field_class}.
1032 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1035 \bt_p{stream_class} must support packets (see
1036 bt_stream_class_set_supports_packets()).
1038 @param[in] stream_class
1039 Stream class of which to set the packet context field class to
1041 @param[in] field_class
1042 New packet context field class of \bt_p{stream_class}.
1044 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1046 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1049 @bt_pre_not_null{stream_class}
1050 @bt_pre_hot{stream_class}
1052 <code>bt_stream_class_supports_packets(stream_class)</code>
1054 @bt_pre_not_null{field_class}
1055 @bt_pre_is_struct_fc{field_class}
1057 \bt_p{field_class}, or any of its contained field classes,
1058 is not already part of a stream class or of an \bt_ev_cls.
1060 If any of the field classes recursively contained in
1061 \bt_p{field_class} has a
1062 \ref api-tir-fc-link "link to another field class", it must honor
1063 the field class link rules.
1065 If any of the field classes recursively contained in
1066 \bt_p{field_class} has a
1067 \ref api-tir-fc-link "link to another field class", it must honor
1068 the field class link rules.
1070 @bt_post_success_frozen{field_class}
1072 @sa bt_stream_class_borrow_packet_context_field_class() —
1073 Borrows the packet context field class of a stream class.
1074 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1075 Borrows the packet context field class of a stream class
1078 extern bt_stream_class_set_field_class_status
1079 bt_stream_class_set_packet_context_field_class(
1080 bt_stream_class
*stream_class
,
1081 bt_field_class
*field_class
);
1085 Borrows the packet context \bt_fc from the stream class
1086 \bt_p{stream_class}.
1088 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1091 If \bt_p{stream_class} has no packet context field class, this function
1094 @param[in] stream_class
1095 Stream class from which to borrow the packet context field class.
1098 \em Borrowed reference of the packet context field class of
1099 \bt_p{stream_class}, or \c NULL if none.
1101 @bt_pre_not_null{stream_class}
1103 @sa bt_stream_class_set_packet_context_field_class() —
1104 Sets the packet context field class of a stream class.
1105 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1106 \c const version of this function.
1108 extern bt_field_class
*
1109 bt_stream_class_borrow_packet_context_field_class(
1110 bt_stream_class
*stream_class
);
1114 Borrows the packet context \bt_fc from the stream class
1115 \bt_p{stream_class} (\c const version).
1117 See bt_stream_class_borrow_packet_context_field_class().
1119 extern const bt_field_class
*
1120 bt_stream_class_borrow_packet_context_field_class_const(
1121 const bt_stream_class
*stream_class
);
1125 Sets the event common context \bt_fc of the stream class
1126 \bt_p{stream_class} to \bt_p{field_class}.
1128 See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class"
1131 @param[in] stream_class
1132 Stream class of which to set the event common context field class to
1134 @param[in] field_class
1135 New event common context field class of \bt_p{stream_class}.
1137 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1139 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1142 @bt_pre_not_null{stream_class}
1143 @bt_pre_hot{stream_class}
1144 @bt_pre_not_null{field_class}
1145 @bt_pre_is_struct_fc{field_class}
1147 \bt_p{field_class}, or any of its contained field classes,
1148 is not already part of a stream class or of an \bt_ev_cls.
1150 If any of the field classes recursively contained in
1151 \bt_p{field_class} has a
1152 \ref api-tir-fc-link "link to another field class", it must honor
1153 the field class link rules.
1155 @bt_post_success_frozen{field_class}
1157 @sa bt_stream_class_borrow_event_common_context_field_class() —
1158 Borrows the event common context field class of a stream class.
1159 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1160 Borrows the event common context field class of a stream class
1163 extern bt_stream_class_set_field_class_status
1164 bt_stream_class_set_event_common_context_field_class(
1165 bt_stream_class
*stream_class
,
1166 bt_field_class
*field_class
);
1170 Borrows the event common context \bt_fc from the stream class
1171 \bt_p{stream_class}.
1173 See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class"
1176 If \bt_p{stream_class} has no event common context field class, this
1177 function returns \c NULL.
1179 @param[in] stream_class
1180 Stream class from which to borrow the event common context
1184 \em Borrowed reference of the event common context field class of
1185 \bt_p{stream_class}, or \c NULL if none.
1187 @bt_pre_not_null{stream_class}
1189 @sa bt_stream_class_set_event_common_context_field_class() —
1190 Sets the event common context field class of a stream class.
1191 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1192 \c const version of this function.
1195 extern bt_field_class
*
1196 bt_stream_class_borrow_event_common_context_field_class(
1197 bt_stream_class
*stream_class
);
1201 Borrows the event common context \bt_fc from the stream class
1202 \bt_p{stream_class} (\c const version()).
1204 See bt_stream_class_borrow_event_common_context_field_class().
1206 extern const bt_field_class
*
1207 bt_stream_class_borrow_event_common_context_field_class_const(
1208 const bt_stream_class
*stream_class
);
1212 Sets whether or not the stream class \bt_p{stream_class}
1213 automatically assigns a numeric ID to an \bt_ev_cls you create and
1216 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1219 @param[in] stream_class
1220 Stream class of which to set whether or not it assigns automatic
1222 @param[in] assigns_automatic_event_class_id
1223 #BT_TRUE to make \bt_p{stream_class} assign automatic event class
1226 @bt_pre_not_null{stream_class}
1227 @bt_pre_hot{stream_class}
1229 @sa bt_stream_class_assigns_automatic_event_class_id() —
1230 Returns whether or not a stream class automatically assigns
1233 extern void bt_stream_class_set_assigns_automatic_event_class_id(
1234 bt_stream_class
*stream_class
,
1235 bt_bool assigns_automatic_event_class_id
);
1239 Returns whether or not the stream class \bt_p{stream_class}
1240 automatically assigns a numeric ID to an \bt_ev_cls you create
1243 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1246 @param[in] stream_class
1247 Stream class of which to get whether or not it assigns automatic
1251 #BT_TRUE if \bt_p{stream_class} automatically
1252 assigns event class IDs.
1254 @bt_pre_not_null{stream_class}
1256 @sa bt_stream_class_set_assigns_automatic_event_class_id() —
1257 Sets whether or not a stream class automatically assigns
1260 extern bt_bool
bt_stream_class_assigns_automatic_event_class_id(
1261 const bt_stream_class
*stream_class
);
1265 Sets whether or not the stream class \bt_p{stream_class}
1266 automatically assigns a numeric ID to a \bt_stream you create from
1269 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1272 @param[in] stream_class
1273 Stream class of which to set whether or not it assigns automatic
1275 @param[in] assigns_automatic_stream_id
1276 #BT_TRUE to make \bt_p{stream_class} assign automatic stream
1279 @bt_pre_not_null{stream_class}
1280 @bt_pre_hot{stream_class}
1282 @sa bt_stream_class_assigns_automatic_stream_id() —
1283 Returns whether or not a stream class automatically assigns
1286 extern void bt_stream_class_set_assigns_automatic_stream_id(
1287 bt_stream_class
*stream_class
, bt_bool assigns_automatic_stream_id
);
1291 Returns whether or not the stream class \bt_p{stream_class}
1292 automatically assigns a numeric ID to a \bt_stream you create
1295 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1298 @param[in] stream_class
1299 Stream class of which to get whether or not it assigns automatic
1303 #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs.
1305 @bt_pre_not_null{stream_class}
1307 @sa bt_stream_class_set_assigns_automatic_stream_id() —
1308 Sets whether or not a stream class automatically assigns
1311 extern bt_bool
bt_stream_class_assigns_automatic_stream_id(
1312 const bt_stream_class
*stream_class
);
1316 Sets whether or not the instances (\bt_p_stream) of the
1317 stream class \bt_p{stream_class} have \bt_p_pkt and, if so,
1318 if those packets have beginning and/or end default
1322 \ref api-tir-stream-cls-prop-supports-pkt "supports packets?",
1323 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?",
1325 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1328 @param[in] stream_class
1329 Stream class of which to set whether or not its streams have
1331 @param[in] supports_packets
1332 #BT_TRUE to make the streams of \bt_p{stream_class} have packets.
1333 @param[in] with_beginning_default_clock_snapshot
1334 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1335 have a beginning default clock snapshot.
1336 @param[in] with_end_default_clock_snapshot
1337 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1338 have an end default clock snapshot.
1340 @bt_pre_not_null{stream_class}
1341 @bt_pre_hot{stream_class}
1343 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1345 \bt_p{supports_packets} is also #BT_TRUE.
1347 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1349 \bt_p{supports_packets} is also #BT_TRUE.
1351 <strong>If \bt_p{with_beginning_default_clock_snapshot} or
1352 \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
1353 \bt_p{stream_class} has a
1354 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1356 @sa bt_stream_class_supports_packets() —
1357 Returns whether or not a stream class's streams have packets.
1358 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1359 Returns whether or not the packets of a stream class's streams
1360 have a beginning default clock snapshot.
1361 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1362 Returns whether or not the packets of a stream class's streams
1363 have an end default clock snapshot.
1365 extern void bt_stream_class_set_supports_packets(
1366 bt_stream_class
*stream_class
, bt_bool supports_packets
,
1367 bt_bool with_beginning_default_clock_snapshot
,
1368 bt_bool with_end_default_clock_snapshot
);
1372 Returns whether or not the instances (\bt_p_stream) of the
1373 stream class \bt_p{stream_class} have \bt_p_pkt.
1375 See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?"
1378 @param[in] stream_class
1379 Stream class of which to get whether or not its streams have
1383 #BT_TRUE if the streams of \bt_p{stream_class} have packets.
1385 @bt_pre_not_null{stream_class}
1387 @sa bt_stream_class_set_supports_packets() —
1388 Sets whether or not a stream class's streams have packets.
1390 extern bt_bool
bt_stream_class_supports_packets(
1391 const bt_stream_class
*stream_class
);
1395 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1396 of the stream class \bt_p{stream_class} have a beginning
1400 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?"
1403 @param[in] stream_class
1404 Stream class of which to get whether or not its streams's packets
1405 have a beginning default clock snapshot.
1408 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a
1409 beginning default clock snapshot.
1411 @bt_pre_not_null{stream_class}
1413 @sa bt_stream_class_set_supports_packets() —
1414 Sets whether or not a stream class's streams have packets.
1415 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1416 Returns whether or not the packets of a stream class's streams
1417 have an end default clock snapshot.
1419 extern bt_bool
bt_stream_class_packets_have_beginning_default_clock_snapshot(
1420 const bt_stream_class
*stream_class
);
1424 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1425 of the stream class \bt_p{stream_class} have an end
1429 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1432 @param[in] stream_class
1433 Stream class of which to get whether or not its streams's packets
1434 have an end default clock snapshot.
1437 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have
1438 an end default clock snapshot.
1440 @bt_pre_not_null{stream_class}
1442 @sa bt_stream_class_set_supports_packets() —
1443 Sets whether or not a stream class's streams have packets.
1444 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1445 Returns whether or not the packets of a stream class's streams
1446 have a beginning default clock snapshot.
1448 extern bt_bool
bt_stream_class_packets_have_end_default_clock_snapshot(
1449 const bt_stream_class
*stream_class
);
1453 Sets whether or not the instances (\bt_p_stream) of the
1454 stream class \bt_p{stream_class} can have discarded events and,
1455 if so, if the \bt_p_disc_ev_msg of those streams have
1456 beginning and end default \bt_p_cs.
1459 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1461 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1464 @param[in] stream_class
1465 Stream class of which to set whether or not its streams can have
1467 @param[in] supports_discarded_events
1468 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1469 have discarded events.
1470 @param[in] with_default_clock_snapshots
1471 #BT_TRUE to make the discarded events messages the streams of
1472 \bt_p{stream_class} have beginning and end default clock snapshots.
1474 @bt_pre_not_null{stream_class}
1475 @bt_pre_hot{stream_class}
1477 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1478 \bt_p{supports_discarded_events} is also #BT_TRUE.
1480 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1481 \bt_p{stream_class} has a
1482 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1484 @sa bt_stream_class_supports_discarded_events() —
1485 Returns whether or not a stream class's streams can have
1487 @sa bt_stream_class_discarded_events_have_default_clock_snapshots() —
1488 Returns whether or not the discarded events messages of a
1489 stream class's streams have beginning and end default clock
1492 extern void bt_stream_class_set_supports_discarded_events(
1493 bt_stream_class
*stream_class
,
1494 bt_bool supports_discarded_events
,
1495 bt_bool with_default_clock_snapshots
);
1499 Returns whether or not the instances (\bt_p_stream) of the
1500 stream class \bt_p{stream_class} can have discarded events.
1503 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1506 @param[in] stream_class
1507 Stream class of which to get whether or not its streams can have
1511 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1514 @bt_pre_not_null{stream_class}
1516 @sa bt_stream_class_set_supports_discarded_events() —
1517 Sets whether or not a stream class's streams can have discarded
1520 extern bt_bool
bt_stream_class_supports_discarded_events(
1521 const bt_stream_class
*stream_class
);
1525 Returns whether or not the \bt_p_disc_ev_msg of the instances
1526 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1527 beginning and end default \bt_p_cs.
1530 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1533 @param[in] stream_class
1534 Stream class of which to get whether or not its streams's discarded
1535 events messages have a beginning and end default clock snapshots.
1538 #BT_TRUE if the discarded events messages of the streams of
1539 \bt_p{stream_class} have beginning and end default clock snapshots.
1541 @bt_pre_not_null{stream_class}
1543 @sa bt_stream_class_set_supports_discarded_events() —
1544 Sets whether or not a stream class's streams can have discarded
1547 extern bt_bool
bt_stream_class_discarded_events_have_default_clock_snapshots(
1548 const bt_stream_class
*stream_class
);
1552 Sets whether or not the instances (\bt_p_stream) of the
1553 stream class \bt_p{stream_class} can have discarded packets and,
1554 if so, if the \bt_p_disc_pkt_msg of those streams have
1555 beginning and end default \bt_p_cs.
1558 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1560 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?"
1563 \bt_p{stream_class} must support packets (see
1564 bt_stream_class_set_supports_packets()).
1566 @param[in] stream_class
1567 Stream class of which to set whether or not its streams can have
1569 @param[in] supports_discarded_packets
1570 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1571 have discarded packets.
1572 @param[in] with_default_clock_snapshots
1573 #BT_TRUE to make the discarded packets messages the streams of
1574 \bt_p{stream_class} have beginning and end default clock snapshots.
1576 @bt_pre_not_null{stream_class}
1577 @bt_pre_hot{stream_class}
1579 <code>bt_stream_class_supports_packets(stream_class)</code>
1582 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1583 \bt_p{supports_discarded_packets} is also #BT_TRUE.
1585 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1586 \bt_p{stream_class} has a
1587 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1589 @sa bt_stream_class_supports_discarded_packets() —
1590 Returns whether or not a stream class's streams can have
1592 @sa bt_stream_class_discarded_packets_have_default_clock_snapshots() —
1593 Returns whether or not the discarded packets messages of a
1594 stream class's streams have beginning and end default clock
1597 extern void bt_stream_class_set_supports_discarded_packets(
1598 bt_stream_class
*stream_class
,
1599 bt_bool supports_discarded_packets
,
1600 bt_bool with_default_clock_snapshots
);
1604 Returns whether or not the instances (\bt_p_stream) of the
1605 stream class \bt_p{stream_class} can have discarded packets.
1608 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1611 @param[in] stream_class
1612 Stream class of which to get whether or not its streams can have
1616 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1619 @bt_pre_not_null{stream_class}
1621 @sa bt_stream_class_set_supports_discarded_packets() —
1622 Sets whether or not a stream class's streams can have discarded
1625 extern bt_bool
bt_stream_class_supports_discarded_packets(
1626 const bt_stream_class
*stream_class
);
1630 Returns whether or not the \bt_p_disc_pkt_msg of the instances
1631 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1632 beginning and end default \bt_p_cs.
1635 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?"
1638 @param[in] stream_class
1639 Stream class of which to get whether or not its streams's discarded
1640 packets messages have a beginning and end default clock snapshots.
1643 #BT_TRUE if the discarded packets messages of the streams of
1644 \bt_p{stream_class} have beginning and end default clock snapshots.
1646 @bt_pre_not_null{stream_class}
1648 @sa bt_stream_class_set_supports_discarded_packets() —
1649 Sets whether or not a stream class's streams can have discarded
1652 extern bt_bool
bt_stream_class_discarded_packets_have_default_clock_snapshots(
1653 const bt_stream_class
*stream_class
);
1657 Sets the user attributes of the stream class \bt_p{stream_class} to
1658 \bt_p{user_attributes}.
1660 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1664 When you create a default stream class with bt_stream_class_create()
1665 or bt_stream_class_create_with_id(), the stream class's initial user
1666 attributes is an empty \bt_map_val. Therefore you can borrow it with
1667 bt_stream_class_borrow_user_attributes() and fill it directly
1668 instead of setting a new one with this function.
1670 @param[in] stream_class
1671 Stream class of which to set the user attributes to
1672 \bt_p{user_attributes}.
1673 @param[in] user_attributes
1674 New user attributes of \bt_p{stream_class}.
1676 @bt_pre_not_null{stream_class}
1677 @bt_pre_hot{stream_class}
1678 @bt_pre_not_null{user_attributes}
1679 @bt_pre_is_map_val{user_attributes}
1681 @sa bt_stream_class_borrow_user_attributes() —
1682 Borrows the user attributes of a stream class.
1684 extern void bt_stream_class_set_user_attributes(
1685 bt_stream_class
*stream_class
, const bt_value
*user_attributes
);
1689 Borrows the user attributes of the stream class \bt_p{stream_class}.
1691 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1695 When you create a default stream class with bt_stream_class_create()
1696 or bt_stream_class_create_with_id(), the stream class's initial user
1697 attributes is an empty \bt_map_val.
1699 @param[in] stream_class
1700 Stream class from which to borrow the user attributes.
1703 User attributes of \bt_p{stream_class} (a \bt_map_val).
1705 @bt_pre_not_null{stream_class}
1707 @sa bt_stream_class_set_user_attributes() —
1708 Sets the user attributes of a stream class.
1709 @sa bt_stream_class_borrow_user_attributes_const() —
1710 \c const version of this function.
1712 extern bt_value
*bt_stream_class_borrow_user_attributes(
1713 bt_stream_class
*stream_class
);
1717 Borrows the user attributes of the stream class \bt_p{stream_class}
1720 See bt_stream_class_borrow_user_attributes().
1722 extern const bt_value
*bt_stream_class_borrow_user_attributes_const(
1723 const bt_stream_class
*stream_class
);
1728 @name Reference count
1734 Increments the \ref api-fund-shared-object "reference count" of
1735 the stream class \bt_p{stream_class}.
1737 @param[in] stream_class
1739 Stream class of which to increment the reference count.
1744 @sa bt_stream_class_put_ref() —
1745 Decrements the reference count of a stream class.
1747 extern void bt_stream_class_get_ref(const bt_stream_class
*stream_class
);
1751 Decrements the \ref api-fund-shared-object "reference count" of
1752 the stream class \bt_p{stream_class}.
1754 @param[in] stream_class
1756 Stream class of which to decrement the reference count.
1761 @sa bt_stream_class_get_ref() —
1762 Increments the reference count of a stream class.
1764 extern void bt_stream_class_put_ref(const bt_stream_class
*stream_class
);
1768 Decrements the reference count of the stream class
1769 \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL.
1771 @param _stream_class
1773 Stream class of which to decrement the reference count.
1775 Can contain \c NULL.
1778 @bt_pre_assign_expr{_stream_class}
1780 #define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \
1782 bt_stream_class_put_ref(_stream_class); \
1783 (_stream_class) = NULL; \
1788 Decrements the reference count of the stream class \bt_p{_dst}, sets
1789 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1791 This macro effectively moves a stream class reference from the expression
1792 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1793 \bt_p{_dst} reference.
1797 Destination expression.
1799 Can contain \c NULL.
1805 Can contain \c NULL.
1808 @bt_pre_assign_expr{_dst}
1809 @bt_pre_assign_expr{_src}
1811 #define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \
1813 bt_stream_class_put_ref(_dst); \
1826 #endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_H */