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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
)
771 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
772 stream class \bt_p{stream_class}.
774 If there's no event class having the numeric ID \bt_p{id} in
775 \bt_p{stream_class}, this function returns \c NULL.
777 @param[in] stream_class
778 Stream class from which to borrow the event class having the
779 numeric ID \bt_p{id}.
781 ID of the event class to borrow from \bt_p{stream_class}.
785 \em Borrowed reference of the event class of
786 \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL
789 The returned pointer remains valid as long as \bt_p{stream_class}
793 @bt_pre_not_null{stream_class}
795 @sa bt_stream_class_borrow_event_class_by_id_const() —
796 \c const version of this function.
798 extern bt_event_class
*
799 bt_stream_class_borrow_event_class_by_id(
800 bt_stream_class
*stream_class
, uint64_t id
) __BT_NOEXCEPT
;
804 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
805 stream class \bt_p{stream_class} (\c const version).
807 See bt_stream_class_borrow_event_class_by_id().
809 extern const bt_event_class
*
810 bt_stream_class_borrow_event_class_by_id_const(
811 const bt_stream_class
*stream_class
, uint64_t id
) __BT_NOEXCEPT
;
822 Returns the numeric ID of the stream class \bt_p{stream_class}.
824 See the \ref api-tir-stream-cls-prop-id "numeric ID" property.
826 @param[in] stream_class
827 Stream class of which to get the numeric ID.
830 Numeric ID of \bt_p{stream_class}.
832 @bt_pre_not_null{stream_class}
834 @sa bt_stream_class_create_with_id() —
835 Creates a stream class with a specific numeric ID and adds it to a
838 extern uint64_t bt_stream_class_get_id(
839 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
843 Status codes for bt_stream_class_set_name().
845 typedef enum bt_stream_class_set_name_status
{
850 BT_STREAM_CLASS_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
856 BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
857 } bt_stream_class_set_name_status
;
861 Sets the name of the stream class \bt_p{stream_class} to
862 a copy of \bt_p{name}.
864 See the \ref api-tir-stream-cls-prop-name "name" property.
866 @param[in] stream_class
867 Stream class of which to set the name to \bt_p{name}.
869 New name of \bt_p{stream_class} (copied).
871 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
873 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
876 @bt_pre_not_null{stream_class}
877 @bt_pre_hot{stream_class}
878 @bt_pre_not_null{name}
880 @sa bt_stream_class_get_name() —
881 Returns the name of a stream class.
883 extern bt_stream_class_set_name_status
bt_stream_class_set_name(
884 bt_stream_class
*stream_class
, const char *name
) __BT_NOEXCEPT
;
888 Returns the name of the stream class \bt_p{stream_class}.
890 See the \ref api-tir-stream-cls-prop-name "name" property.
892 If \bt_p{stream_class} has no name, this function returns \c NULL.
894 @param[in] stream_class
895 Stream class of which to get the name.
899 Name of \bt_p{stream_class}, or \c NULL if none.
901 The returned pointer remains valid as long as \bt_p{stream_class}
905 @bt_pre_not_null{stream_class}
907 @sa bt_stream_class_set_name() —
908 Sets the name of a stream class.
910 extern const char *bt_stream_class_get_name(
911 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
915 Status codes for bt_stream_class_set_default_clock_class().
917 typedef enum bt_stream_class_set_default_clock_class_status
{
922 BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
923 } bt_stream_class_set_default_clock_class_status
;
927 Sets the default \bt_clock_cls of the stream class
928 \bt_p{stream_class} to \bt_p{clock_class}.
930 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
933 @param[in] stream_class
934 Stream class of which to set the default clock class to
936 @param[in] clock_class
937 New default clock class of \bt_p{stream_class}.
939 @retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
942 @bt_pre_not_null{stream_class}
943 @bt_pre_hot{stream_class}
944 @bt_pre_not_null{clock_class}
946 @sa bt_stream_class_borrow_default_clock_class() —
947 Borrows the default clock class of a stream class.
948 @sa bt_stream_class_borrow_default_clock_class_const() —
949 Borrows the default clock class of a stream class (\c const version).
951 extern bt_stream_class_set_default_clock_class_status
952 bt_stream_class_set_default_clock_class(
953 bt_stream_class
*stream_class
,
954 bt_clock_class
*clock_class
) __BT_NOEXCEPT
;
958 Borrows the default \bt_clock_cls from the stream class
961 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
964 If \bt_p{stream_class} has no default clock class, this function
967 @param[in] stream_class
968 Stream class from which to borrow the default clock class.
971 \em Borrowed reference of the default clock class of
972 \bt_p{stream_class}, or \c NULL if none.
974 @bt_pre_not_null{stream_class}
976 @sa bt_stream_class_set_default_clock_class() —
977 Sets the default clock class of a stream class.
978 @sa bt_stream_class_borrow_default_clock_class_const() —
979 \c const version of this function.
981 extern bt_clock_class
*bt_stream_class_borrow_default_clock_class(
982 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
986 Borrows the default \bt_clock_cls from the stream class
987 \bt_p{stream_class} (\c const version).
989 See bt_stream_class_borrow_default_clock_class().
991 extern const bt_clock_class
*
992 bt_stream_class_borrow_default_clock_class_const(
993 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
997 Status codes for bt_stream_class_set_packet_context_field_class()
998 and bt_stream_class_set_event_common_context_field_class().
1000 typedef enum bt_stream_class_set_field_class_status
{
1005 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1011 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1012 } bt_stream_class_set_field_class_status
;
1016 Sets the packet context \bt_fc of the stream class
1017 \bt_p{stream_class} to \bt_p{field_class}.
1019 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1022 \bt_p{stream_class} must support packets (see
1023 bt_stream_class_set_supports_packets()).
1025 @param[in] stream_class
1026 Stream class of which to set the packet context field class to
1028 @param[in] field_class
1029 New packet context field class of \bt_p{stream_class}.
1031 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1033 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1036 @bt_pre_not_null{stream_class}
1037 @bt_pre_hot{stream_class}
1039 <code>bt_stream_class_supports_packets(stream_class)</code>
1041 @bt_pre_not_null{field_class}
1042 @bt_pre_is_struct_fc{field_class}
1044 \bt_p{field_class}, or any of its contained field classes,
1045 is not already part of a stream class or of an \bt_ev_cls.
1047 If any of the field classes recursively contained in
1048 \bt_p{field_class} has a
1049 \ref api-tir-fc-link "link to another field class", it must honor
1050 the field class link rules.
1052 If any of the field classes recursively contained in
1053 \bt_p{field_class} has a
1054 \ref api-tir-fc-link "link to another field class", it must honor
1055 the field class link rules.
1057 @bt_post_success_frozen{field_class}
1059 @sa bt_stream_class_borrow_packet_context_field_class() —
1060 Borrows the packet context field class of a stream class.
1061 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1062 Borrows the packet context field class of a stream class
1065 extern bt_stream_class_set_field_class_status
1066 bt_stream_class_set_packet_context_field_class(
1067 bt_stream_class
*stream_class
,
1068 bt_field_class
*field_class
) __BT_NOEXCEPT
;
1072 Borrows the packet context \bt_fc from the stream class
1073 \bt_p{stream_class}.
1075 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1078 If \bt_p{stream_class} has no packet context field class, this function
1081 @param[in] stream_class
1082 Stream class from which to borrow the packet context field class.
1085 \em Borrowed reference of the packet context field class of
1086 \bt_p{stream_class}, or \c NULL if none.
1088 @bt_pre_not_null{stream_class}
1090 @sa bt_stream_class_set_packet_context_field_class() —
1091 Sets the packet context field class of a stream class.
1092 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1093 \c const version of this function.
1095 extern bt_field_class
*
1096 bt_stream_class_borrow_packet_context_field_class(
1097 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1101 Borrows the packet context \bt_fc from the stream class
1102 \bt_p{stream_class} (\c const version).
1104 See bt_stream_class_borrow_packet_context_field_class().
1106 extern const bt_field_class
*
1107 bt_stream_class_borrow_packet_context_field_class_const(
1108 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1112 Sets the event common context \bt_fc of the stream class
1113 \bt_p{stream_class} to \bt_p{field_class}.
1115 See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class"
1118 @param[in] stream_class
1119 Stream class of which to set the event common context field class to
1121 @param[in] field_class
1122 New event common context field class of \bt_p{stream_class}.
1124 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1126 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1129 @bt_pre_not_null{stream_class}
1130 @bt_pre_hot{stream_class}
1131 @bt_pre_not_null{field_class}
1132 @bt_pre_is_struct_fc{field_class}
1134 \bt_p{field_class}, or any of its contained field classes,
1135 is not already part of a stream class or of an \bt_ev_cls.
1137 If any of the field classes recursively contained in
1138 \bt_p{field_class} has a
1139 \ref api-tir-fc-link "link to another field class", it must honor
1140 the field class link rules.
1142 @bt_post_success_frozen{field_class}
1144 @sa bt_stream_class_borrow_event_common_context_field_class() —
1145 Borrows the event common context field class of a stream class.
1146 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1147 Borrows the event common context field class of a stream class
1150 extern bt_stream_class_set_field_class_status
1151 bt_stream_class_set_event_common_context_field_class(
1152 bt_stream_class
*stream_class
,
1153 bt_field_class
*field_class
) __BT_NOEXCEPT
;
1157 Borrows the event common context \bt_fc from the stream class
1158 \bt_p{stream_class}.
1160 See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class"
1163 If \bt_p{stream_class} has no event common context field class, this
1164 function returns \c NULL.
1166 @param[in] stream_class
1167 Stream class from which to borrow the event common context
1171 \em Borrowed reference of the event common context field class of
1172 \bt_p{stream_class}, or \c NULL if none.
1174 @bt_pre_not_null{stream_class}
1176 @sa bt_stream_class_set_event_common_context_field_class() —
1177 Sets the event common context field class of a stream class.
1178 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1179 \c const version of this function.
1182 extern bt_field_class
*
1183 bt_stream_class_borrow_event_common_context_field_class(
1184 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1188 Borrows the event common context \bt_fc from the stream class
1189 \bt_p{stream_class} (\c const version()).
1191 See bt_stream_class_borrow_event_common_context_field_class().
1193 extern const bt_field_class
*
1194 bt_stream_class_borrow_event_common_context_field_class_const(
1195 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1199 Sets whether or not the stream class \bt_p{stream_class}
1200 automatically assigns a numeric ID to an \bt_ev_cls you create and
1203 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1206 @param[in] stream_class
1207 Stream class of which to set whether or not it assigns automatic
1209 @param[in] assigns_automatic_event_class_id
1210 #BT_TRUE to make \bt_p{stream_class} assign automatic event class
1213 @bt_pre_not_null{stream_class}
1214 @bt_pre_hot{stream_class}
1216 @sa bt_stream_class_assigns_automatic_event_class_id() —
1217 Returns whether or not a stream class automatically assigns
1220 extern void bt_stream_class_set_assigns_automatic_event_class_id(
1221 bt_stream_class
*stream_class
,
1222 bt_bool assigns_automatic_event_class_id
) __BT_NOEXCEPT
;
1226 Returns whether or not the stream class \bt_p{stream_class}
1227 automatically assigns a numeric ID to an \bt_ev_cls you create
1230 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1233 @param[in] stream_class
1234 Stream class of which to get whether or not it assigns automatic
1238 #BT_TRUE if \bt_p{stream_class} automatically
1239 assigns event class IDs.
1241 @bt_pre_not_null{stream_class}
1243 @sa bt_stream_class_set_assigns_automatic_event_class_id() —
1244 Sets whether or not a stream class automatically assigns
1247 extern bt_bool
bt_stream_class_assigns_automatic_event_class_id(
1248 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1252 Sets whether or not the stream class \bt_p{stream_class}
1253 automatically assigns a numeric ID to a \bt_stream you create from
1256 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1259 @param[in] stream_class
1260 Stream class of which to set whether or not it assigns automatic
1262 @param[in] assigns_automatic_stream_id
1263 #BT_TRUE to make \bt_p{stream_class} assign automatic stream
1266 @bt_pre_not_null{stream_class}
1267 @bt_pre_hot{stream_class}
1269 @sa bt_stream_class_assigns_automatic_stream_id() —
1270 Returns whether or not a stream class automatically assigns
1273 extern void bt_stream_class_set_assigns_automatic_stream_id(
1274 bt_stream_class
*stream_class
,
1275 bt_bool assigns_automatic_stream_id
) __BT_NOEXCEPT
;
1279 Returns whether or not the stream class \bt_p{stream_class}
1280 automatically assigns a numeric ID to a \bt_stream you create
1283 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1286 @param[in] stream_class
1287 Stream class of which to get whether or not it assigns automatic
1291 #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs.
1293 @bt_pre_not_null{stream_class}
1295 @sa bt_stream_class_set_assigns_automatic_stream_id() —
1296 Sets whether or not a stream class automatically assigns
1299 extern bt_bool
bt_stream_class_assigns_automatic_stream_id(
1300 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1304 Sets whether or not the instances (\bt_p_stream) of the
1305 stream class \bt_p{stream_class} have \bt_p_pkt and, if so,
1306 if those packets have beginning and/or end default
1310 \ref api-tir-stream-cls-prop-supports-pkt "supports packets?",
1311 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?",
1313 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1316 @param[in] stream_class
1317 Stream class of which to set whether or not its streams have
1319 @param[in] supports_packets
1320 #BT_TRUE to make the streams of \bt_p{stream_class} have packets.
1321 @param[in] with_beginning_default_clock_snapshot
1322 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1323 have a beginning default clock snapshot.
1324 @param[in] with_end_default_clock_snapshot
1325 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1326 have an end default clock snapshot.
1328 @bt_pre_not_null{stream_class}
1329 @bt_pre_hot{stream_class}
1331 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1333 \bt_p{supports_packets} is also #BT_TRUE.
1335 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1337 \bt_p{supports_packets} is also #BT_TRUE.
1339 <strong>If \bt_p{with_beginning_default_clock_snapshot} or
1340 \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
1341 \bt_p{stream_class} has a
1342 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1344 @sa bt_stream_class_supports_packets() —
1345 Returns whether or not a stream class's streams have packets.
1346 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1347 Returns whether or not the packets of a stream class's streams
1348 have a beginning default clock snapshot.
1349 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1350 Returns whether or not the packets of a stream class's streams
1351 have an end default clock snapshot.
1353 extern void bt_stream_class_set_supports_packets(
1354 bt_stream_class
*stream_class
, bt_bool supports_packets
,
1355 bt_bool with_beginning_default_clock_snapshot
,
1356 bt_bool with_end_default_clock_snapshot
) __BT_NOEXCEPT
;
1360 Returns whether or not the instances (\bt_p_stream) of the
1361 stream class \bt_p{stream_class} have \bt_p_pkt.
1363 See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?"
1366 @param[in] stream_class
1367 Stream class of which to get whether or not its streams have
1371 #BT_TRUE if the streams of \bt_p{stream_class} have packets.
1373 @bt_pre_not_null{stream_class}
1375 @sa bt_stream_class_set_supports_packets() —
1376 Sets whether or not a stream class's streams have packets.
1378 extern bt_bool
bt_stream_class_supports_packets(
1379 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1383 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1384 of the stream class \bt_p{stream_class} have a beginning
1388 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?"
1391 @param[in] stream_class
1392 Stream class of which to get whether or not its streams's packets
1393 have a beginning default clock snapshot.
1396 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a
1397 beginning default clock snapshot.
1399 @bt_pre_not_null{stream_class}
1401 @sa bt_stream_class_set_supports_packets() —
1402 Sets whether or not a stream class's streams have packets.
1403 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1404 Returns whether or not the packets of a stream class's streams
1405 have an end default clock snapshot.
1407 extern bt_bool
bt_stream_class_packets_have_beginning_default_clock_snapshot(
1408 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1412 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1413 of the stream class \bt_p{stream_class} have an end
1417 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1420 @param[in] stream_class
1421 Stream class of which to get whether or not its streams's packets
1422 have an end default clock snapshot.
1425 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have
1426 an end default clock snapshot.
1428 @bt_pre_not_null{stream_class}
1430 @sa bt_stream_class_set_supports_packets() —
1431 Sets whether or not a stream class's streams have packets.
1432 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1433 Returns whether or not the packets of a stream class's streams
1434 have a beginning default clock snapshot.
1436 extern bt_bool
bt_stream_class_packets_have_end_default_clock_snapshot(
1437 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1441 Sets whether or not the instances (\bt_p_stream) of the
1442 stream class \bt_p{stream_class} can have discarded events and,
1443 if so, if the \bt_p_disc_ev_msg of those streams have
1444 beginning and end default \bt_p_cs.
1447 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1449 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1452 @param[in] stream_class
1453 Stream class of which to set whether or not its streams can have
1455 @param[in] supports_discarded_events
1456 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1457 have discarded events.
1458 @param[in] with_default_clock_snapshots
1459 #BT_TRUE to make the discarded events messages the streams of
1460 \bt_p{stream_class} have beginning and end default clock snapshots.
1462 @bt_pre_not_null{stream_class}
1463 @bt_pre_hot{stream_class}
1465 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1466 \bt_p{supports_discarded_events} is also #BT_TRUE.
1468 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1469 \bt_p{stream_class} has a
1470 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1472 @sa bt_stream_class_supports_discarded_events() —
1473 Returns whether or not a stream class's streams can have
1475 @sa bt_stream_class_discarded_events_have_default_clock_snapshots() —
1476 Returns whether or not the discarded events messages of a
1477 stream class's streams have beginning and end default clock
1480 extern void bt_stream_class_set_supports_discarded_events(
1481 bt_stream_class
*stream_class
,
1482 bt_bool supports_discarded_events
,
1483 bt_bool with_default_clock_snapshots
) __BT_NOEXCEPT
;
1487 Returns whether or not the instances (\bt_p_stream) of the
1488 stream class \bt_p{stream_class} can have discarded events.
1491 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1494 @param[in] stream_class
1495 Stream class of which to get whether or not its streams can have
1499 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1502 @bt_pre_not_null{stream_class}
1504 @sa bt_stream_class_set_supports_discarded_events() —
1505 Sets whether or not a stream class's streams can have discarded
1508 extern bt_bool
bt_stream_class_supports_discarded_events(
1509 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1513 Returns whether or not the \bt_p_disc_ev_msg of the instances
1514 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1515 beginning and end default \bt_p_cs.
1518 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1521 @param[in] stream_class
1522 Stream class of which to get whether or not its streams's discarded
1523 events messages have a beginning and end default clock snapshots.
1526 #BT_TRUE if the discarded events messages of the streams of
1527 \bt_p{stream_class} have beginning and end default clock snapshots.
1529 @bt_pre_not_null{stream_class}
1531 @sa bt_stream_class_set_supports_discarded_events() —
1532 Sets whether or not a stream class's streams can have discarded
1535 extern bt_bool
bt_stream_class_discarded_events_have_default_clock_snapshots(
1536 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1540 Sets whether or not the instances (\bt_p_stream) of the
1541 stream class \bt_p{stream_class} can have discarded packets and,
1542 if so, if the \bt_p_disc_pkt_msg of those streams have
1543 beginning and end default \bt_p_cs.
1546 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1548 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?"
1551 \bt_p{stream_class} must support packets (see
1552 bt_stream_class_set_supports_packets()).
1554 @param[in] stream_class
1555 Stream class of which to set whether or not its streams can have
1557 @param[in] supports_discarded_packets
1558 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1559 have discarded packets.
1560 @param[in] with_default_clock_snapshots
1561 #BT_TRUE to make the discarded packets messages the streams of
1562 \bt_p{stream_class} have beginning and end default clock snapshots.
1564 @bt_pre_not_null{stream_class}
1565 @bt_pre_hot{stream_class}
1567 <code>bt_stream_class_supports_packets(stream_class)</code>
1570 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1571 \bt_p{supports_discarded_packets} is also #BT_TRUE.
1573 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1574 \bt_p{stream_class} has a
1575 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1577 @sa bt_stream_class_supports_discarded_packets() —
1578 Returns whether or not a stream class's streams can have
1580 @sa bt_stream_class_discarded_packets_have_default_clock_snapshots() —
1581 Returns whether or not the discarded packets messages of a
1582 stream class's streams have beginning and end default clock
1585 extern void bt_stream_class_set_supports_discarded_packets(
1586 bt_stream_class
*stream_class
,
1587 bt_bool supports_discarded_packets
,
1588 bt_bool with_default_clock_snapshots
) __BT_NOEXCEPT
;
1592 Returns whether or not the instances (\bt_p_stream) of the
1593 stream class \bt_p{stream_class} can have discarded packets.
1596 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1599 @param[in] stream_class
1600 Stream class of which to get whether or not its streams can have
1604 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1607 @bt_pre_not_null{stream_class}
1609 @sa bt_stream_class_set_supports_discarded_packets() —
1610 Sets whether or not a stream class's streams can have discarded
1613 extern bt_bool
bt_stream_class_supports_discarded_packets(
1614 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1618 Returns whether or not the \bt_p_disc_pkt_msg of the instances
1619 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1620 beginning and end default \bt_p_cs.
1623 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?"
1626 @param[in] stream_class
1627 Stream class of which to get whether or not its streams's discarded
1628 packets messages have a beginning and end default clock snapshots.
1631 #BT_TRUE if the discarded packets messages of the streams of
1632 \bt_p{stream_class} have beginning and end default clock snapshots.
1634 @bt_pre_not_null{stream_class}
1636 @sa bt_stream_class_set_supports_discarded_packets() —
1637 Sets whether or not a stream class's streams can have discarded
1640 extern bt_bool
bt_stream_class_discarded_packets_have_default_clock_snapshots(
1641 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1645 Sets the user attributes of the stream class \bt_p{stream_class} to
1646 \bt_p{user_attributes}.
1648 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1652 When you create a default stream class with bt_stream_class_create()
1653 or bt_stream_class_create_with_id(), the stream class's initial user
1654 attributes is an empty \bt_map_val. Therefore you can borrow it with
1655 bt_stream_class_borrow_user_attributes() and fill it directly
1656 instead of setting a new one with this function.
1658 @param[in] stream_class
1659 Stream class of which to set the user attributes to
1660 \bt_p{user_attributes}.
1661 @param[in] user_attributes
1662 New user attributes of \bt_p{stream_class}.
1664 @bt_pre_not_null{stream_class}
1665 @bt_pre_hot{stream_class}
1666 @bt_pre_not_null{user_attributes}
1667 @bt_pre_is_map_val{user_attributes}
1669 @sa bt_stream_class_borrow_user_attributes() —
1670 Borrows the user attributes of a stream class.
1672 extern void bt_stream_class_set_user_attributes(
1673 bt_stream_class
*stream_class
,
1674 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
1678 Borrows the user attributes of the stream class \bt_p{stream_class}.
1680 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1684 When you create a default stream class with bt_stream_class_create()
1685 or bt_stream_class_create_with_id(), the stream class's initial user
1686 attributes is an empty \bt_map_val.
1688 @param[in] stream_class
1689 Stream class from which to borrow the user attributes.
1692 User attributes of \bt_p{stream_class} (a \bt_map_val).
1694 @bt_pre_not_null{stream_class}
1696 @sa bt_stream_class_set_user_attributes() —
1697 Sets the user attributes of a stream class.
1698 @sa bt_stream_class_borrow_user_attributes_const() —
1699 \c const version of this function.
1701 extern bt_value
*bt_stream_class_borrow_user_attributes(
1702 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1706 Borrows the user attributes of the stream class \bt_p{stream_class}
1709 See bt_stream_class_borrow_user_attributes().
1711 extern const bt_value
*bt_stream_class_borrow_user_attributes_const(
1712 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1717 @name Reference count
1723 Increments the \ref api-fund-shared-object "reference count" of
1724 the stream class \bt_p{stream_class}.
1726 @param[in] stream_class
1728 Stream class of which to increment the reference count.
1733 @sa bt_stream_class_put_ref() —
1734 Decrements the reference count of a stream class.
1736 extern void bt_stream_class_get_ref(
1737 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1741 Decrements the \ref api-fund-shared-object "reference count" of
1742 the stream class \bt_p{stream_class}.
1744 @param[in] stream_class
1746 Stream class of which to decrement the reference count.
1751 @sa bt_stream_class_get_ref() —
1752 Increments the reference count of a stream class.
1754 extern void bt_stream_class_put_ref(
1755 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1759 Decrements the reference count of the stream class
1760 \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL.
1762 @param _stream_class
1764 Stream class of which to decrement the reference count.
1766 Can contain \c NULL.
1769 @bt_pre_assign_expr{_stream_class}
1771 #define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \
1773 bt_stream_class_put_ref(_stream_class); \
1774 (_stream_class) = NULL; \
1779 Decrements the reference count of the stream class \bt_p{_dst}, sets
1780 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1782 This macro effectively moves a stream class reference from the expression
1783 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1784 \bt_p{_dst} reference.
1788 Destination expression.
1790 Can contain \c NULL.
1796 Can contain \c NULL.
1799 @bt_pre_assign_expr{_dst}
1800 @bt_pre_assign_expr{_src}
1802 #define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \
1804 bt_stream_class_put_ref(_dst); \
1817 #endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_H */