2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_STREAM_CLASS_H
8 #define BABELTRACE2_TRACE_IR_STREAM_CLASS_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-stream-cls Stream class
29 Class of \bt_p_stream.
31 A <strong><em>stream class</em></strong> is the class of \bt_p_stream:
33 @image html trace-structure.png
35 In the illustration above, notice that:
37 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages".
39 The sequence always starts with a \bt_sb_msg and ends with a
42 - A stream is an instance of a stream class.
44 A stream class is a \ref api-tir "trace IR" metadata object.
46 A stream class is a \ref api-fund-shared-object "shared object": get a
47 new reference with bt_stream_class_get_ref() and put an existing
48 reference with bt_stream_class_put_ref().
50 Some library functions \ref api-fund-freezing "freeze" stream classes on
51 success. The documentation of those functions indicate this
52 postcondition. You can still create and add an \bt_p_ev_cls to a frozen
53 stream class with bt_event_class_create() or
54 bt_event_class_create_with_id().
56 The type of a stream class is #bt_stream_class.
58 A \bt_trace_cls contains stream classes. All the stream classes of a
59 given trace class have unique
60 \ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class
61 which contains a stream class with bt_stream_class_borrow_trace_class()
62 or bt_stream_class_borrow_trace_class_const().
64 A stream class contains \bt_p_ev_cls. All the event classes of a given
65 stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get
66 the number of event classes in a stream class with
67 bt_stream_class_get_event_class_count(). Borrow a specific event class
68 from a stream class with bt_stream_class_borrow_event_class_by_index(),
69 bt_stream_class_borrow_event_class_by_index_const(),
70 bt_stream_class_borrow_event_class_by_id(), and
71 bt_stream_class_borrow_event_class_by_id_const().
73 A stream class controls what its instances (\bt_p_stream) support:
76 <dt>Default clock</dt>
78 By default, a stream class's streams do not have default clocks.
80 Set the default \bt_clock_cls of a stream class with
81 bt_stream_class_set_default_clock_class(). This makes all its
82 streams have their own default clock.
85 <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt>
87 By default, a stream class's streams do not support \bt_p_pkt.
89 In other words, you cannot create a packet for such a stream,
90 therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this
93 Enable packet support for a stream class's streams with
94 bt_stream_class_set_supports_packets().
96 bt_stream_class_set_supports_packets() also configures whether or
97 not the packets of the stream class's instances have beginning
98 and/or end default \bt_p_cs.
101 <dt>Discarded events</dt>
103 By default, a stream class's streams do not support discarded
106 In other words, you cannot create \bt_p_disc_ev_msg for such a
109 Enable discarded events support for a stream class's streams with
110 bt_stream_class_set_supports_discarded_events().
112 bt_stream_class_set_supports_discarded_events() also configures
113 whether or not the discarded events messages of the stream class's
114 instances have beginning and end default \bt_p_cs to indicate the
115 discarded events time range.
118 <dt>Discarded packets</dt>
120 By default, a stream class's streams do not support discarded
123 In other words, you cannot create \bt_p_disc_pkt_msg for such a
126 Enable discarded packets support for a stream class's streams with
127 bt_stream_class_set_supports_discarded_packets(). This also implies
128 that you must enable packet support with
129 bt_stream_class_set_supports_packets().
131 bt_stream_class_set_supports_discarded_packets() also configures
132 whether or not the discarded packets messages of the stream class's
133 instances have beginning and end \bt_p_cs to indicate the
134 discarded packets time range.
138 Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a
139 stream class get automatic numeric IDs with
140 bt_stream_class_set_assigns_automatic_event_class_id() and
141 bt_stream_class_set_assigns_automatic_stream_id().
143 To create a default stream class:
147 If bt_trace_class_assigns_automatic_stream_class_id() returns
148 #BT_TRUE (the default) for the trace class to use
150 <dd>Use bt_stream_class_create().</dd>
153 If bt_trace_class_assigns_automatic_stream_class_id() returns
154 #BT_FALSE for the trace class to use
156 <dd>Use bt_stream_class_create_with_id().</dd>
161 A stream class has the following properties:
164 <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt>
166 Numeric ID, unique amongst the numeric IDs of the stream class's
167 \bt_trace_cls's stream classes.
169 Depending on whether or not the stream class's trace class
170 automatically assigns \bt_ev_cls IDs
171 (see bt_trace_class_assigns_automatic_stream_class_id()),
172 set the stream class's numeric ID on creation with
173 bt_stream_class_create() or bt_stream_class_create_with_id().
175 You cannot change the numeric ID once the stream class is created.
177 Get a stream class's numeric ID with bt_stream_class_get_id().
180 <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
182 Name of the stream class.
184 Use bt_stream_class_set_name() and bt_stream_class_get_name().
188 \anchor api-tir-stream-cls-prop-def-clock-cls
189 \bt_dt_opt Default clock class
192 Default \bt_clock_cls of the stream class.
194 As of \bt_name_version_min_maj, a stream class either has a default
195 clock class or none: it cannot have more than one clock class.
197 When a stream class has a default clock class, then all its
198 instances (\bt_p_stream) have a default clock which is an instance
199 of the stream class's default clock class.
201 Use bt_stream_class_set_default_clock_class(),
202 bt_stream_class_borrow_default_clock_class(), and
203 bt_stream_class_borrow_default_clock_class_const().
207 \anchor api-tir-stream-cls-prop-pc-fc
208 \bt_dt_opt Packet context field class
211 \bt_c_pkt context \bt_fc of the stream class.
213 This property is only relevant if the stream class
214 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
216 The context of a \bt_pkt contains data which is common to all the
219 Use bt_stream_class_set_packet_context_field_class()
220 bt_stream_class_borrow_packet_context_field_class(),
221 and bt_stream_class_borrow_packet_context_field_class_const().
225 \anchor api-tir-stream-cls-prop-ecc-fc
226 \bt_dt_opt Event common context field class
229 \bt_c_ev common context \bt_fc of the stream class.
231 The common context of an \bt_ev contains contextual data of which
232 the layout is common to all the stream class's \bt_p_ev_cls.
234 Use bt_stream_class_set_event_common_context_field_class()
235 bt_stream_class_borrow_event_common_context_field_class(),
236 and bt_stream_class_borrow_event_common_context_field_class_const().
240 \anchor api-tir-stream-cls-prop-auto-ec-id
241 Assigns automatic event class IDs?
244 Whether or not the \bt_p_ev_cls you create and add to the stream
245 class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically.
247 Depending on the value of this property, to create an event class
248 and add it to the stream class:
253 Use bt_event_class_create().
258 Use bt_event_class_create_with_id().
262 Use bt_stream_class_set_assigns_automatic_event_class_id()
263 and bt_stream_class_assigns_automatic_event_class_id().
267 \anchor api-tir-stream-cls-prop-auto-stream-id
268 Assigns automatic stream IDs?
271 Whether or not the streams you create from the stream class
272 get \ref api-tir-stream-prop-id "numeric IDs" automatically.
274 Depending on the value of this property, to create a stream
275 from the stream class:
280 Use bt_stream_create().
285 Use bt_stream_create_with_id().
289 Use bt_stream_class_set_assigns_automatic_stream_id()
290 and bt_stream_class_assigns_automatic_stream_id().
294 \anchor api-tir-stream-cls-prop-supports-pkt
298 Whether or not the streams you create from the stream class
301 If a stream has packets, then all the stream's \bt_p_ev are
302 conceptually contained within packets, which means you must
303 create \bt_p_ev_msg for such streams with
304 bt_message_event_create_with_packet() or
305 bt_message_event_create_with_packet_and_default_clock_snapshot()
306 instead of bt_message_event_create() or
307 bt_message_event_create_with_default_clock_snapshot().
309 It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to
310 indicate where packets begin and end within the stream's
311 \ref api-msg-seq "message sequence".
313 Use bt_stream_class_set_supports_packets() and
314 bt_stream_class_supports_packets().
318 \anchor api-tir-stream-cls-prop-pkt-beg-cs
319 Packets have a beginning default clock snapshot?
322 Whether or not the \bt_p_pkt of the streams you create from the
323 stream class have beginning default \bt_p_cs.
325 This property is only relevant if the stream class
326 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
328 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
330 If the stream packets have a beginning default clock snapshot, then
331 you must create \bt_p_pb_msg with
332 bt_message_packet_beginning_create_with_default_clock_snapshot()
333 instead of bt_message_packet_beginning_create().
335 Use bt_stream_class_set_supports_packets() and
336 bt_stream_class_packets_have_beginning_default_clock_snapshot().
340 \anchor api-tir-stream-cls-prop-pkt-end-cs
341 Packets have an end default clock snapshot?
344 Whether or not the \bt_p_pkt of the streams you create from the
345 stream class have end default \bt_p_cs.
347 This property is only relevant if the stream class
348 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
350 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
352 If the stream packets have an end default clock snapshot, then you
353 must create \bt_p_pe_msg with
354 bt_message_packet_end_create_with_default_clock_snapshot() instead
355 of bt_message_packet_end_create().
357 Use bt_stream_class_set_supports_packets() and
358 bt_stream_class_packets_have_end_default_clock_snapshot().
362 \anchor api-tir-stream-cls-prop-supports-disc-ev
363 Supports discarded events?
366 Whether or not the streams you create from the stream class can have
369 If the stream class supports discarded events, then you can create
370 \bt_p_disc_ev_msg for this stream.
372 Use bt_stream_class_set_supports_discarded_events()
373 and bt_stream_class_supports_discarded_events().
377 \anchor api-tir-stream-cls-prop-disc-ev-cs
378 Discarded events have default clock snapshots?
381 Whether or not the stream's \bt_p_disc_ev_msg have
382 default beginning and end \bt_p_cs to indicate the discarded events
385 This property is only relevant if the stream class
386 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events"
388 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
390 If the stream's discarded events messages have beginning and end
391 default clock snapshots, then you must create them with
392 bt_message_discarded_events_create_with_default_clock_snapshots()
393 instead of bt_message_discarded_events_create().
395 Use bt_stream_class_set_supports_discarded_events()
396 and bt_stream_class_discarded_events_have_default_clock_snapshots().
400 \anchor api-tir-stream-cls-prop-supports-disc-pkt
401 Supports discarded packets?
404 Whether or not the streams you create from the stream class can have
407 This property is only relevant if the stream class
408 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
410 If the stream class supports discarded packets, then you can create
411 \bt_p_disc_pkt_msg for this stream.
413 Use bt_stream_class_set_supports_discarded_packets()
414 and bt_stream_class_supports_discarded_packets().
418 \anchor api-tir-stream-cls-prop-disc-pkt-cs
419 Discarded packets have default clock snapshots?
422 Whether or not the stream's \bt_p_disc_pkt_msg have
423 default beginning and end \bt_p_cs to indicate the discarded
426 This property is only relevant if the stream class
427 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets"
429 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
431 If the stream's discarded packets messages have default clock
432 snapshots, then you must create them with
433 bt_message_discarded_packets_create_with_default_clock_snapshots()
434 instead of bt_message_discarded_packets_create().
436 Use bt_stream_class_set_supports_discarded_packets()
437 and bt_stream_class_discarded_packets_have_default_clock_snapshots().
441 \anchor api-tir-stream-cls-prop-user-attrs
442 \bt_dt_opt User attributes
445 User attributes of the stream class.
447 User attributes are custom attributes attached to a stream class.
449 Use bt_stream_class_set_user_attributes(),
450 bt_stream_class_borrow_user_attributes(), and
451 bt_stream_class_borrow_user_attributes_const().
462 @typedef struct bt_stream_class bt_stream_class;
477 Creates a default stream class and adds it to the \bt_trace_cls
482 Only use this function if
485 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
490 Otherwise, use bt_stream_class_create_with_id().
493 On success, the returned stream class has the following property values:
500 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
501 <td>Automatically assigned by \bt_p{trace_class}
503 <td>\ref api-tir-stream-cls-prop-name "Name"
506 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
509 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
512 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
515 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
518 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
521 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
524 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
527 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
530 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
533 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
536 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
539 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
542 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
543 <td>Empty \bt_map_val
546 @param[in] trace_class
547 Trace class to add the created stream class to.
550 New stream class reference, or \c NULL on memory error.
552 @bt_pre_not_null{trace_class}
554 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
557 @bt_post_success_frozen{trace_class}
559 @sa bt_stream_class_create_with_id() —
560 Creates a stream class with a specific numeric ID and adds it to a
563 extern bt_stream_class
*bt_stream_class_create(
564 bt_trace_class
*trace_class
);
568 Creates a default stream class with the numeric ID \bt_p{id} and adds
569 it to the \bt_trace_cls \bt_p{trace_class}.
573 Only use this function if
576 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
581 Otherwise, use bt_stream_class_create().
584 On success, the returned stream class has the following property values:
591 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
594 <td>\ref api-tir-stream-cls-prop-name "Name"
597 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
600 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
603 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
606 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
609 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
612 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
615 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
618 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
621 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
624 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
627 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
630 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
633 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
634 <td>Empty \bt_map_val
637 @param[in] trace_class
638 Trace class to add the created stream class to.
640 Numeric ID of the stream class to create and add to
644 New stream class reference, or \c NULL on memory error.
646 @bt_pre_not_null{trace_class}
648 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
651 \bt_p{trace_class} does not contain a stream class with the numeric
654 @bt_post_success_frozen{trace_class}
656 @sa bt_stream_class_create() —
657 Creates a stream class with an automatic numeric ID and adds it to a
660 extern bt_stream_class
*bt_stream_class_create_with_id(
661 bt_trace_class
*trace_class
, uint64_t id
);
666 @name Trace class access
672 Borrows the \bt_trace_cls which contains the stream class
675 @param[in] stream_class
676 Stream class from which to borrow the trace class which contains it.
679 Trace class which contains \bt_p{stream_class}.
681 @bt_pre_not_null{stream_class}
683 @sa bt_stream_class_borrow_trace_class_const() —
684 \c const version of this function.
686 extern bt_trace_class
*bt_stream_class_borrow_trace_class(
687 bt_stream_class
*stream_class
);
691 Borrows the \bt_trace_cls which contains the stream class
692 \bt_p{stream_class} (\c const version).
694 See bt_stream_class_borrow_trace_class().
696 extern const bt_trace_class
*bt_stream_class_borrow_trace_class_const(
697 const bt_stream_class
*stream_class
);
702 @name Event class access
708 Returns the number of \bt_p_ev_cls contained in the stream
709 class \bt_p{stream_class}.
711 @param[in] stream_class
712 Stream class of which to get the number of contained event classes.
715 Number of contained event classes in \bt_p{stream_class}.
717 @bt_pre_not_null{stream_class}
719 extern uint64_t bt_stream_class_get_event_class_count(
720 const bt_stream_class
*stream_class
);
724 Borrows the \bt_ev_cls at index \bt_p{index} from the
725 stream class \bt_p{stream_class}.
727 @param[in] stream_class
728 Stream class from which to borrow the event class at index
731 Index of the event class to borrow from \bt_p{stream_class}.
735 \em Borrowed reference of the event class of
736 \bt_p{stream_class} at index \bt_p{index}.
738 The returned pointer remains valid as long as \bt_p{stream_class}
742 @bt_pre_not_null{stream_class}
744 \bt_p{index} is less than the number of event classes in
745 \bt_p{stream_class} (as returned by
746 bt_stream_class_get_event_class_count()).
748 @sa bt_stream_class_get_event_class_count() —
749 Returns the number of event classes contained in a stream class.
750 @sa bt_stream_class_borrow_event_class_by_index_const() —
751 \c const version of this function.
753 extern bt_event_class
*
754 bt_stream_class_borrow_event_class_by_index(
755 bt_stream_class
*stream_class
, uint64_t index
);
759 Borrows the \bt_ev_cls at index \bt_p{index} from the
760 stream class \bt_p{stream_class} (\c const version).
762 See bt_stream_class_borrow_event_class_by_index().
764 extern const bt_event_class
*
765 bt_stream_class_borrow_event_class_by_index_const(
766 const bt_stream_class
*stream_class
, uint64_t index
);
770 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
771 stream class \bt_p{stream_class}.
773 If there's no event class having the numeric ID \bt_p{id} in
774 \bt_p{stream_class}, this function returns \c NULL.
776 @param[in] stream_class
777 Stream class from which to borrow the event class having the
778 numeric ID \bt_p{id}.
780 ID of the event class to borrow from \bt_p{stream_class}.
784 \em Borrowed reference of the event class of
785 \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL
788 The returned pointer remains valid as long as \bt_p{stream_class}
792 @bt_pre_not_null{stream_class}
794 @sa bt_stream_class_borrow_event_class_by_id_const() —
795 \c const version of this function.
797 extern bt_event_class
*
798 bt_stream_class_borrow_event_class_by_id(
799 bt_stream_class
*stream_class
, uint64_t id
);
803 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
804 stream class \bt_p{stream_class} (\c const version).
806 See bt_stream_class_borrow_event_class_by_id().
808 extern const bt_event_class
*
809 bt_stream_class_borrow_event_class_by_id_const(
810 const bt_stream_class
*stream_class
, uint64_t id
);
821 Returns the numeric ID of the stream class \bt_p{stream_class}.
823 See the \ref api-tir-stream-cls-prop-id "numeric ID" property.
825 @param[in] stream_class
826 Stream class of which to get the numeric ID.
829 Numeric ID of \bt_p{stream_class}.
831 @bt_pre_not_null{stream_class}
833 @sa bt_stream_class_create_with_id() —
834 Creates a stream class with a specific numeric ID and adds it to a
837 extern uint64_t bt_stream_class_get_id(
838 const bt_stream_class
*stream_class
);
842 Status codes for bt_stream_class_set_name().
844 typedef enum bt_stream_class_set_name_status
{
849 BT_STREAM_CLASS_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
855 BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
856 } bt_stream_class_set_name_status
;
860 Sets the name of the stream class \bt_p{stream_class} to
861 a copy of \bt_p{name}.
863 See the \ref api-tir-stream-cls-prop-name "name" property.
865 @param[in] stream_class
866 Stream class of which to set the name to \bt_p{name}.
868 New name of \bt_p{stream_class} (copied).
870 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
872 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
875 @bt_pre_not_null{stream_class}
876 @bt_pre_hot{stream_class}
877 @bt_pre_not_null{name}
879 @sa bt_stream_class_get_name() —
880 Returns the name of a stream class.
882 extern bt_stream_class_set_name_status
bt_stream_class_set_name(
883 bt_stream_class
*stream_class
, const char *name
);
887 Returns the name of the stream class \bt_p{stream_class}.
889 See the \ref api-tir-stream-cls-prop-name "name" property.
891 If \bt_p{stream_class} has no name, this function returns \c NULL.
893 @param[in] stream_class
894 Stream class of which to get the name.
898 Name of \bt_p{stream_class}, or \c NULL if none.
900 The returned pointer remains valid as long as \bt_p{stream_class}
904 @bt_pre_not_null{stream_class}
906 @sa bt_stream_class_set_name() —
907 Sets the name of a stream class.
909 extern const char *bt_stream_class_get_name(
910 const bt_stream_class
*stream_class
);
914 Status codes for bt_stream_class_set_default_clock_class().
916 typedef enum bt_stream_class_set_default_clock_class_status
{
921 BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
922 } bt_stream_class_set_default_clock_class_status
;
926 Sets the default \bt_clock_cls of the stream class
927 \bt_p{stream_class} to \bt_p{clock_class}.
929 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
932 @param[in] stream_class
933 Stream class of which to set the default clock class to
935 @param[in] clock_class
936 New default clock class of \bt_p{stream_class}.
938 @retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
941 @bt_pre_not_null{stream_class}
942 @bt_pre_hot{stream_class}
943 @bt_pre_not_null{clock_class}
945 @sa bt_stream_class_borrow_default_clock_class() —
946 Borrows the default clock class of a stream class.
947 @sa bt_stream_class_borrow_default_clock_class_const() —
948 Borrows the default clock class of a stream class (\c const version).
950 extern bt_stream_class_set_default_clock_class_status
951 bt_stream_class_set_default_clock_class(
952 bt_stream_class
*stream_class
,
953 bt_clock_class
*clock_class
);
957 Borrows the default \bt_clock_cls from the stream class
960 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
963 If \bt_p{stream_class} has no default clock class, this function
966 @param[in] stream_class
967 Stream class from which to borrow the default clock class.
970 \em Borrowed reference of the default clock class of
971 \bt_p{stream_class}, or \c NULL if none.
973 @bt_pre_not_null{stream_class}
975 @sa bt_stream_class_set_default_clock_class() —
976 Sets the default clock class of a stream class.
977 @sa bt_stream_class_borrow_default_clock_class_const() —
978 \c const version of this function.
980 extern bt_clock_class
*bt_stream_class_borrow_default_clock_class(
981 bt_stream_class
*stream_class
);
985 Borrows the default \bt_clock_cls from the stream class
986 \bt_p{stream_class} (\c const version).
988 See bt_stream_class_borrow_default_clock_class().
990 extern const bt_clock_class
*
991 bt_stream_class_borrow_default_clock_class_const(
992 const bt_stream_class
*stream_class
);
996 Status codes for bt_stream_class_set_packet_context_field_class()
997 and bt_stream_class_set_event_common_context_field_class().
999 typedef enum bt_stream_class_set_field_class_status
{
1004 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1010 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1011 } bt_stream_class_set_field_class_status
;
1015 Sets the packet context \bt_fc of the stream class
1016 \bt_p{stream_class} to \bt_p{field_class}.
1018 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1021 \bt_p{stream_class} must support packets (see
1022 bt_stream_class_set_supports_packets()).
1024 @param[in] stream_class
1025 Stream class of which to set the packet context field class to
1027 @param[in] field_class
1028 New packet context field class of \bt_p{stream_class}.
1030 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1032 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1035 @bt_pre_not_null{stream_class}
1036 @bt_pre_hot{stream_class}
1038 <code>bt_stream_class_supports_packets(stream_class)</code>
1040 @bt_pre_not_null{field_class}
1041 @bt_pre_is_struct_fc{field_class}
1043 \bt_p{field_class}, or any of its contained field classes,
1044 is not already part of a stream class or of an \bt_ev_cls.
1046 If any of the field classes recursively contained in
1047 \bt_p{field_class} has a
1048 \ref api-tir-fc-link "link to another field class", it must honor
1049 the field class link rules.
1051 If any of the field classes recursively contained in
1052 \bt_p{field_class} has a
1053 \ref api-tir-fc-link "link to another field class", it must honor
1054 the field class link rules.
1056 @bt_post_success_frozen{field_class}
1058 @sa bt_stream_class_borrow_packet_context_field_class() —
1059 Borrows the packet context field class of a stream class.
1060 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1061 Borrows the packet context field class of a stream class
1064 extern bt_stream_class_set_field_class_status
1065 bt_stream_class_set_packet_context_field_class(
1066 bt_stream_class
*stream_class
,
1067 bt_field_class
*field_class
);
1071 Borrows the packet context \bt_fc from the stream class
1072 \bt_p{stream_class}.
1074 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1077 If \bt_p{stream_class} has no packet context field class, this function
1080 @param[in] stream_class
1081 Stream class from which to borrow the packet context field class.
1084 \em Borrowed reference of the packet context field class of
1085 \bt_p{stream_class}, or \c NULL if none.
1087 @bt_pre_not_null{stream_class}
1089 @sa bt_stream_class_set_packet_context_field_class() —
1090 Sets the packet context field class of a stream class.
1091 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1092 \c const version of this function.
1094 extern bt_field_class
*
1095 bt_stream_class_borrow_packet_context_field_class(
1096 bt_stream_class
*stream_class
);
1100 Borrows the packet context \bt_fc from the stream class
1101 \bt_p{stream_class} (\c const version).
1103 See bt_stream_class_borrow_packet_context_field_class().
1105 extern const bt_field_class
*
1106 bt_stream_class_borrow_packet_context_field_class_const(
1107 const bt_stream_class
*stream_class
);
1111 Sets the event common context \bt_fc of the stream class
1112 \bt_p{stream_class} to \bt_p{field_class}.
1114 See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class"
1117 @param[in] stream_class
1118 Stream class of which to set the event common context field class to
1120 @param[in] field_class
1121 New event common context field class of \bt_p{stream_class}.
1123 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1125 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1128 @bt_pre_not_null{stream_class}
1129 @bt_pre_hot{stream_class}
1130 @bt_pre_not_null{field_class}
1131 @bt_pre_is_struct_fc{field_class}
1133 \bt_p{field_class}, or any of its contained field classes,
1134 is not already part of a stream class or of an \bt_ev_cls.
1136 If any of the field classes recursively contained in
1137 \bt_p{field_class} has a
1138 \ref api-tir-fc-link "link to another field class", it must honor
1139 the field class link rules.
1141 @bt_post_success_frozen{field_class}
1143 @sa bt_stream_class_borrow_event_common_context_field_class() —
1144 Borrows the event common context field class of a stream class.
1145 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1146 Borrows the event common context field class of a stream class
1149 extern bt_stream_class_set_field_class_status
1150 bt_stream_class_set_event_common_context_field_class(
1151 bt_stream_class
*stream_class
,
1152 bt_field_class
*field_class
);
1156 Borrows the event common context \bt_fc from the stream class
1157 \bt_p{stream_class}.
1159 See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class"
1162 If \bt_p{stream_class} has no event common context field class, this
1163 function returns \c NULL.
1165 @param[in] stream_class
1166 Stream class from which to borrow the event common context
1170 \em Borrowed reference of the event common context field class of
1171 \bt_p{stream_class}, or \c NULL if none.
1173 @bt_pre_not_null{stream_class}
1175 @sa bt_stream_class_set_event_common_context_field_class() —
1176 Sets the event common context field class of a stream class.
1177 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1178 \c const version of this function.
1181 extern bt_field_class
*
1182 bt_stream_class_borrow_event_common_context_field_class(
1183 bt_stream_class
*stream_class
);
1187 Borrows the event common context \bt_fc from the stream class
1188 \bt_p{stream_class} (\c const version()).
1190 See bt_stream_class_borrow_event_common_context_field_class().
1192 extern const bt_field_class
*
1193 bt_stream_class_borrow_event_common_context_field_class_const(
1194 const bt_stream_class
*stream_class
);
1198 Sets whether or not the stream class \bt_p{stream_class}
1199 automatically assigns a numeric ID to an \bt_ev_cls you create and
1202 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1205 @param[in] stream_class
1206 Stream class of which to set whether or not it assigns automatic
1208 @param[in] assigns_automatic_event_class_id
1209 #BT_TRUE to make \bt_p{stream_class} assign automatic event class
1212 @bt_pre_not_null{stream_class}
1213 @bt_pre_hot{stream_class}
1215 @sa bt_stream_class_assigns_automatic_event_class_id() —
1216 Returns whether or not a stream class automatically assigns
1219 extern void bt_stream_class_set_assigns_automatic_event_class_id(
1220 bt_stream_class
*stream_class
,
1221 bt_bool assigns_automatic_event_class_id
);
1225 Returns whether or not the stream class \bt_p{stream_class}
1226 automatically assigns a numeric ID to an \bt_ev_cls you create
1229 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1232 @param[in] stream_class
1233 Stream class of which to get whether or not it assigns automatic
1237 #BT_TRUE if \bt_p{stream_class} automatically
1238 assigns event class IDs.
1240 @bt_pre_not_null{stream_class}
1242 @sa bt_stream_class_set_assigns_automatic_event_class_id() —
1243 Sets whether or not a stream class automatically assigns
1246 extern bt_bool
bt_stream_class_assigns_automatic_event_class_id(
1247 const bt_stream_class
*stream_class
);
1251 Sets whether or not the stream class \bt_p{stream_class}
1252 automatically assigns a numeric ID to a \bt_stream you create from
1255 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1258 @param[in] stream_class
1259 Stream class of which to set whether or not it assigns automatic
1261 @param[in] assigns_automatic_stream_id
1262 #BT_TRUE to make \bt_p{stream_class} assign automatic stream
1265 @bt_pre_not_null{stream_class}
1266 @bt_pre_hot{stream_class}
1268 @sa bt_stream_class_assigns_automatic_stream_id() —
1269 Returns whether or not a stream class automatically assigns
1272 extern void bt_stream_class_set_assigns_automatic_stream_id(
1273 bt_stream_class
*stream_class
, bt_bool assigns_automatic_stream_id
);
1277 Returns whether or not the stream class \bt_p{stream_class}
1278 automatically assigns a numeric ID to a \bt_stream you create
1281 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1284 @param[in] stream_class
1285 Stream class of which to get whether or not it assigns automatic
1289 #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs.
1291 @bt_pre_not_null{stream_class}
1293 @sa bt_stream_class_set_assigns_automatic_stream_id() —
1294 Sets whether or not a stream class automatically assigns
1297 extern bt_bool
bt_stream_class_assigns_automatic_stream_id(
1298 const bt_stream_class
*stream_class
);
1302 Sets whether or not the instances (\bt_p_stream) of the
1303 stream class \bt_p{stream_class} have \bt_p_pkt and, if so,
1304 if those packets have beginning and/or end default
1308 \ref api-tir-stream-cls-prop-supports-pkt "supports packets?",
1309 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?",
1311 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1314 @param[in] stream_class
1315 Stream class of which to set whether or not its streams have
1317 @param[in] supports_packets
1318 #BT_TRUE to make the streams of \bt_p{stream_class} have packets.
1319 @param[in] with_beginning_default_clock_snapshot
1320 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1321 have a beginning default clock snapshot.
1322 @param[in] with_end_default_clock_snapshot
1323 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1324 have an end default clock snapshot.
1326 @bt_pre_not_null{stream_class}
1327 @bt_pre_hot{stream_class}
1329 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1331 \bt_p{supports_packets} is also #BT_TRUE.
1333 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1335 \bt_p{supports_packets} is also #BT_TRUE.
1337 <strong>If \bt_p{with_beginning_default_clock_snapshot} or
1338 \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
1339 \bt_p{stream_class} has a
1340 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1342 @sa bt_stream_class_supports_packets() —
1343 Returns whether or not a stream class's streams have packets.
1344 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1345 Returns whether or not the packets of a stream class's streams
1346 have a beginning default clock snapshot.
1347 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1348 Returns whether or not the packets of a stream class's streams
1349 have an end default clock snapshot.
1351 extern void bt_stream_class_set_supports_packets(
1352 bt_stream_class
*stream_class
, bt_bool supports_packets
,
1353 bt_bool with_beginning_default_clock_snapshot
,
1354 bt_bool with_end_default_clock_snapshot
);
1358 Returns whether or not the instances (\bt_p_stream) of the
1359 stream class \bt_p{stream_class} have \bt_p_pkt.
1361 See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?"
1364 @param[in] stream_class
1365 Stream class of which to get whether or not its streams have
1369 #BT_TRUE if the streams of \bt_p{stream_class} have packets.
1371 @bt_pre_not_null{stream_class}
1373 @sa bt_stream_class_set_supports_packets() —
1374 Sets whether or not a stream class's streams have packets.
1376 extern bt_bool
bt_stream_class_supports_packets(
1377 const bt_stream_class
*stream_class
);
1381 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1382 of the stream class \bt_p{stream_class} have a beginning
1386 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?"
1389 @param[in] stream_class
1390 Stream class of which to get whether or not its streams's packets
1391 have a beginning default clock snapshot.
1394 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a
1395 beginning default clock snapshot.
1397 @bt_pre_not_null{stream_class}
1399 @sa bt_stream_class_set_supports_packets() —
1400 Sets whether or not a stream class's streams have packets.
1401 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1402 Returns whether or not the packets of a stream class's streams
1403 have an end default clock snapshot.
1405 extern bt_bool
bt_stream_class_packets_have_beginning_default_clock_snapshot(
1406 const bt_stream_class
*stream_class
);
1410 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1411 of the stream class \bt_p{stream_class} have an end
1415 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1418 @param[in] stream_class
1419 Stream class of which to get whether or not its streams's packets
1420 have an end default clock snapshot.
1423 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have
1424 an end default clock snapshot.
1426 @bt_pre_not_null{stream_class}
1428 @sa bt_stream_class_set_supports_packets() —
1429 Sets whether or not a stream class's streams have packets.
1430 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1431 Returns whether or not the packets of a stream class's streams
1432 have a beginning default clock snapshot.
1434 extern bt_bool
bt_stream_class_packets_have_end_default_clock_snapshot(
1435 const bt_stream_class
*stream_class
);
1439 Sets whether or not the instances (\bt_p_stream) of the
1440 stream class \bt_p{stream_class} can have discarded events and,
1441 if so, if the \bt_p_disc_ev_msg of those streams have
1442 beginning and end default \bt_p_cs.
1445 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1447 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1450 @param[in] stream_class
1451 Stream class of which to set whether or not its streams can have
1453 @param[in] supports_discarded_events
1454 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1455 have discarded events.
1456 @param[in] with_default_clock_snapshots
1457 #BT_TRUE to make the discarded events messages the streams of
1458 \bt_p{stream_class} have beginning and end default clock snapshots.
1460 @bt_pre_not_null{stream_class}
1461 @bt_pre_hot{stream_class}
1463 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1464 \bt_p{supports_discarded_events} is also #BT_TRUE.
1466 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1467 \bt_p{stream_class} has a
1468 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1470 @sa bt_stream_class_supports_discarded_events() —
1471 Returns whether or not a stream class's streams can have
1473 @sa bt_stream_class_discarded_events_have_default_clock_snapshots() —
1474 Returns whether or not the discarded events messages of a
1475 stream class's streams have beginning and end default clock
1478 extern void bt_stream_class_set_supports_discarded_events(
1479 bt_stream_class
*stream_class
,
1480 bt_bool supports_discarded_events
,
1481 bt_bool with_default_clock_snapshots
);
1485 Returns whether or not the instances (\bt_p_stream) of the
1486 stream class \bt_p{stream_class} can have discarded events.
1489 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1492 @param[in] stream_class
1493 Stream class of which to get whether or not its streams can have
1497 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1500 @bt_pre_not_null{stream_class}
1502 @sa bt_stream_class_set_supports_discarded_events() —
1503 Sets whether or not a stream class's streams can have discarded
1506 extern bt_bool
bt_stream_class_supports_discarded_events(
1507 const bt_stream_class
*stream_class
);
1511 Returns whether or not the \bt_p_disc_ev_msg of the instances
1512 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1513 beginning and end default \bt_p_cs.
1516 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1519 @param[in] stream_class
1520 Stream class of which to get whether or not its streams's discarded
1521 events messages have a beginning and end default clock snapshots.
1524 #BT_TRUE if the discarded events messages of the streams of
1525 \bt_p{stream_class} have beginning and end default clock snapshots.
1527 @bt_pre_not_null{stream_class}
1529 @sa bt_stream_class_set_supports_discarded_events() —
1530 Sets whether or not a stream class's streams can have discarded
1533 extern bt_bool
bt_stream_class_discarded_events_have_default_clock_snapshots(
1534 const bt_stream_class
*stream_class
);
1538 Sets whether or not the instances (\bt_p_stream) of the
1539 stream class \bt_p{stream_class} can have discarded packets and,
1540 if so, if the \bt_p_disc_pkt_msg of those streams have
1541 beginning and end default \bt_p_cs.
1544 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1546 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?"
1549 \bt_p{stream_class} must support packets (see
1550 bt_stream_class_set_supports_packets()).
1552 @param[in] stream_class
1553 Stream class of which to set whether or not its streams can have
1555 @param[in] supports_discarded_packets
1556 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1557 have discarded packets.
1558 @param[in] with_default_clock_snapshots
1559 #BT_TRUE to make the discarded packets messages the streams of
1560 \bt_p{stream_class} have beginning and end default clock snapshots.
1562 @bt_pre_not_null{stream_class}
1563 @bt_pre_hot{stream_class}
1565 <code>bt_stream_class_supports_packets(stream_class)</code>
1568 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1569 \bt_p{supports_discarded_packets} is also #BT_TRUE.
1571 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1572 \bt_p{stream_class} has a
1573 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1575 @sa bt_stream_class_supports_discarded_packets() —
1576 Returns whether or not a stream class's streams can have
1578 @sa bt_stream_class_discarded_packets_have_default_clock_snapshots() —
1579 Returns whether or not the discarded packets messages of a
1580 stream class's streams have beginning and end default clock
1583 extern void bt_stream_class_set_supports_discarded_packets(
1584 bt_stream_class
*stream_class
,
1585 bt_bool supports_discarded_packets
,
1586 bt_bool with_default_clock_snapshots
);
1590 Returns whether or not the instances (\bt_p_stream) of the
1591 stream class \bt_p{stream_class} can have discarded packets.
1594 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1597 @param[in] stream_class
1598 Stream class of which to get whether or not its streams can have
1602 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1605 @bt_pre_not_null{stream_class}
1607 @sa bt_stream_class_set_supports_discarded_packets() —
1608 Sets whether or not a stream class's streams can have discarded
1611 extern bt_bool
bt_stream_class_supports_discarded_packets(
1612 const bt_stream_class
*stream_class
);
1616 Returns whether or not the \bt_p_disc_pkt_msg of the instances
1617 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1618 beginning and end default \bt_p_cs.
1621 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?"
1624 @param[in] stream_class
1625 Stream class of which to get whether or not its streams's discarded
1626 packets messages have a beginning and end default clock snapshots.
1629 #BT_TRUE if the discarded packets messages of the streams of
1630 \bt_p{stream_class} have beginning and end default clock snapshots.
1632 @bt_pre_not_null{stream_class}
1634 @sa bt_stream_class_set_supports_discarded_packets() —
1635 Sets whether or not a stream class's streams can have discarded
1638 extern bt_bool
bt_stream_class_discarded_packets_have_default_clock_snapshots(
1639 const bt_stream_class
*stream_class
);
1643 Sets the user attributes of the stream class \bt_p{stream_class} to
1644 \bt_p{user_attributes}.
1646 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1650 When you create a default stream class with bt_stream_class_create()
1651 or bt_stream_class_create_with_id(), the stream class's initial user
1652 attributes is an empty \bt_map_val. Therefore you can borrow it with
1653 bt_stream_class_borrow_user_attributes() and fill it directly
1654 instead of setting a new one with this function.
1656 @param[in] stream_class
1657 Stream class of which to set the user attributes to
1658 \bt_p{user_attributes}.
1659 @param[in] user_attributes
1660 New user attributes of \bt_p{stream_class}.
1662 @bt_pre_not_null{stream_class}
1663 @bt_pre_hot{stream_class}
1664 @bt_pre_not_null{user_attributes}
1665 @bt_pre_is_map_val{user_attributes}
1667 @sa bt_stream_class_borrow_user_attributes() —
1668 Borrows the user attributes of a stream class.
1670 extern void bt_stream_class_set_user_attributes(
1671 bt_stream_class
*stream_class
, const bt_value
*user_attributes
);
1675 Borrows the user attributes of the stream class \bt_p{stream_class}.
1677 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1681 When you create a default stream class with bt_stream_class_create()
1682 or bt_stream_class_create_with_id(), the stream class's initial user
1683 attributes is an empty \bt_map_val.
1685 @param[in] stream_class
1686 Stream class from which to borrow the user attributes.
1689 User attributes of \bt_p{stream_class} (a \bt_map_val).
1691 @bt_pre_not_null{stream_class}
1693 @sa bt_stream_class_set_user_attributes() —
1694 Sets the user attributes of a stream class.
1695 @sa bt_stream_class_borrow_user_attributes_const() —
1696 \c const version of this function.
1698 extern bt_value
*bt_stream_class_borrow_user_attributes(
1699 bt_stream_class
*stream_class
);
1703 Borrows the user attributes of the stream class \bt_p{stream_class}
1706 See bt_stream_class_borrow_user_attributes().
1708 extern const bt_value
*bt_stream_class_borrow_user_attributes_const(
1709 const bt_stream_class
*stream_class
);
1714 @name Reference count
1720 Increments the \ref api-fund-shared-object "reference count" of
1721 the stream class \bt_p{stream_class}.
1723 @param[in] stream_class
1725 Stream class of which to increment the reference count.
1730 @sa bt_stream_class_put_ref() —
1731 Decrements the reference count of a stream class.
1733 extern void bt_stream_class_get_ref(const bt_stream_class
*stream_class
);
1737 Decrements the \ref api-fund-shared-object "reference count" of
1738 the stream class \bt_p{stream_class}.
1740 @param[in] stream_class
1742 Stream class of which to decrement the reference count.
1747 @sa bt_stream_class_get_ref() —
1748 Increments the reference count of a stream class.
1750 extern void bt_stream_class_put_ref(const bt_stream_class
*stream_class
);
1754 Decrements the reference count of the stream class
1755 \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL.
1757 @param _stream_class
1759 Stream class of which to decrement the reference count.
1761 Can contain \c NULL.
1764 @bt_pre_assign_expr{_stream_class}
1766 #define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \
1768 bt_stream_class_put_ref(_stream_class); \
1769 (_stream_class) = NULL; \
1774 Decrements the reference count of the stream class \bt_p{_dst}, sets
1775 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1777 This macro effectively moves a stream class reference from the expression
1778 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1779 \bt_p{_dst} reference.
1783 Destination expression.
1785 Can contain \c NULL.
1791 Can contain \c NULL.
1794 @bt_pre_assign_expr{_dst}
1795 @bt_pre_assign_expr{_src}
1797 #define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \
1799 bt_stream_class_put_ref(_dst); \
1812 #endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_H */