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().
181 \anchor api-tir-stream-cls-prop-ns
183 (only available when the parent \bt_trace_cls was created
184 from a \bt_comp which belongs to a trace processing \bt_graph
185 with the effective \bt_mip version 1)
188 Namespace of the stream class.
190 Use bt_stream_class_set_namespace() and
191 bt_stream_class_get_namespace().
194 <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
196 Name of the stream class.
198 Use bt_stream_class_set_name() and bt_stream_class_get_name().
202 \anchor api-tir-stream-cls-prop-uid
204 (only available when the parent \bt_trace_cls was created
205 from a \bt_comp which belongs to a trace processing \bt_graph
206 with the effective \bt_mip version 1)
209 <a href="https://en.wikipedia.org/wiki/Unique_identifier">Unique identifier</a>
210 (UID) of the stream class.
212 Use bt_stream_class_set_uid() and
213 bt_stream_class_get_uid().
217 \anchor api-tir-stream-cls-prop-def-clock-cls
218 \bt_dt_opt Default clock class
221 Default \bt_clock_cls of the stream class.
223 As of \bt_name_version_min_maj, a stream class either has a default
224 clock class or none: it cannot have more than one clock class.
226 When a stream class has a default clock class, then all its
227 instances (\bt_p_stream) have a default clock which is an instance
228 of the stream class's default clock class.
230 Use bt_stream_class_set_default_clock_class(),
231 bt_stream_class_borrow_default_clock_class(), and
232 bt_stream_class_borrow_default_clock_class_const().
236 \anchor api-tir-stream-cls-prop-pc-fc
237 \bt_dt_opt Packet context field class
240 \bt_c_pkt context \bt_fc of the stream class.
242 This property is only relevant if the stream class
243 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
245 The context of a \bt_pkt contains data which is common to all the
248 Use bt_stream_class_set_packet_context_field_class()
249 bt_stream_class_borrow_packet_context_field_class(),
250 and bt_stream_class_borrow_packet_context_field_class_const().
254 \anchor api-tir-stream-cls-prop-ecc-fc
255 \bt_dt_opt Event common context field class
258 \bt_c_ev common context \bt_fc of the stream class.
260 The common context of an \bt_ev contains contextual data of which
261 the layout is common to all the stream class's \bt_p_ev_cls.
263 Use bt_stream_class_set_event_common_context_field_class()
264 bt_stream_class_borrow_event_common_context_field_class(),
265 and bt_stream_class_borrow_event_common_context_field_class_const().
269 \anchor api-tir-stream-cls-prop-auto-ec-id
270 Assigns automatic event class IDs?
273 Whether or not the \bt_p_ev_cls you create and add to the stream
274 class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically.
276 Depending on the value of this property, to create an event class
277 and add it to the stream class:
282 Use bt_event_class_create().
287 Use bt_event_class_create_with_id().
291 Use bt_stream_class_set_assigns_automatic_event_class_id()
292 and bt_stream_class_assigns_automatic_event_class_id().
296 \anchor api-tir-stream-cls-prop-auto-stream-id
297 Assigns automatic stream IDs?
300 Whether or not the streams you create from the stream class
301 get \ref api-tir-stream-prop-id "numeric IDs" automatically.
303 Depending on the value of this property, to create a stream
304 from the stream class:
309 Use bt_stream_create().
314 Use bt_stream_create_with_id().
318 Use bt_stream_class_set_assigns_automatic_stream_id()
319 and bt_stream_class_assigns_automatic_stream_id().
323 \anchor api-tir-stream-cls-prop-supports-pkt
327 Whether or not the streams you create from the stream class
330 If a stream has packets, then all the stream's \bt_p_ev are
331 conceptually contained within packets, which means you must
332 create \bt_p_ev_msg for such streams with
333 bt_message_event_create_with_packet() or
334 bt_message_event_create_with_packet_and_default_clock_snapshot()
335 instead of bt_message_event_create() or
336 bt_message_event_create_with_default_clock_snapshot().
338 It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to
339 indicate where packets begin and end within the stream's
340 \ref api-msg-seq "message sequence".
342 Use bt_stream_class_set_supports_packets() and
343 bt_stream_class_supports_packets().
347 \anchor api-tir-stream-cls-prop-pkt-beg-cs
348 Packets have a beginning default clock snapshot?
351 Whether or not the \bt_p_pkt of the streams you create from the
352 stream class have beginning default \bt_p_cs.
354 This property is only relevant if the stream class
355 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
357 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
359 If the stream packets have a beginning default clock snapshot, then
360 you must create \bt_p_pb_msg with
361 bt_message_packet_beginning_create_with_default_clock_snapshot()
362 instead of bt_message_packet_beginning_create().
364 Use bt_stream_class_set_supports_packets() and
365 bt_stream_class_packets_have_beginning_default_clock_snapshot().
369 \anchor api-tir-stream-cls-prop-pkt-end-cs
370 Packets have an end default clock snapshot?
373 Whether or not the \bt_p_pkt of the streams you create from the
374 stream class have end default \bt_p_cs.
376 This property is only relevant if the stream class
377 \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
379 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
381 If the stream packets have an end default clock snapshot, then you
382 must create \bt_p_pe_msg with
383 bt_message_packet_end_create_with_default_clock_snapshot() instead
384 of bt_message_packet_end_create().
386 Use bt_stream_class_set_supports_packets() and
387 bt_stream_class_packets_have_end_default_clock_snapshot().
391 \anchor api-tir-stream-cls-prop-supports-disc-ev
392 Supports discarded events?
395 Whether or not the streams you create from the stream class can have
398 If the stream class supports discarded events, then you can create
399 \bt_p_disc_ev_msg for this stream.
401 Use bt_stream_class_set_supports_discarded_events()
402 and bt_stream_class_supports_discarded_events().
406 \anchor api-tir-stream-cls-prop-disc-ev-cs
407 Discarded events have default clock snapshots?
410 Whether or not the stream's \bt_p_disc_ev_msg have
411 default beginning and end \bt_p_cs to indicate the discarded events
414 This property is only relevant if the stream class
415 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events"
417 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
419 If the stream's discarded events messages have beginning and end
420 default clock snapshots, then you must create them with
421 bt_message_discarded_events_create_with_default_clock_snapshots()
422 instead of bt_message_discarded_events_create().
424 Use bt_stream_class_set_supports_discarded_events()
425 and bt_stream_class_discarded_events_have_default_clock_snapshots().
429 \anchor api-tir-stream-cls-prop-supports-disc-pkt
430 Supports discarded packets?
433 Whether or not the streams you create from the stream class can have
436 This property is only relevant if the stream class
437 \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
439 If the stream class supports discarded packets, then you can create
440 \bt_p_disc_pkt_msg for this stream.
442 Use bt_stream_class_set_supports_discarded_packets()
443 and bt_stream_class_supports_discarded_packets().
447 \anchor api-tir-stream-cls-prop-disc-pkt-cs
448 Discarded packets have default clock snapshots?
451 Whether or not the stream's \bt_p_disc_pkt_msg have
452 default beginning and end \bt_p_cs to indicate the discarded
455 This property is only relevant if the stream class
456 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets"
458 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
460 If the stream's discarded packets messages have default clock
461 snapshots, then you must create them with
462 bt_message_discarded_packets_create_with_default_clock_snapshots()
463 instead of bt_message_discarded_packets_create().
465 Use bt_stream_class_set_supports_discarded_packets()
466 and bt_stream_class_discarded_packets_have_default_clock_snapshots().
470 \anchor api-tir-stream-cls-prop-user-attrs
471 \bt_dt_opt User attributes
474 User attributes of the stream class.
476 User attributes are custom attributes attached to a stream class.
478 Use bt_stream_class_set_user_attributes(),
479 bt_stream_class_borrow_user_attributes(), and
480 bt_stream_class_borrow_user_attributes_const().
491 @typedef struct bt_stream_class bt_stream_class;
506 Creates a default stream class and adds it to the \bt_trace_cls
511 Only use this function if
514 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
519 Otherwise, use bt_stream_class_create_with_id().
522 On success, the returned stream class has the following property values:
529 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
530 <td>Automatically assigned by \bt_p{trace_class}
532 <td>\bt_mip version 1: \ref api-tir-stream-cls-prop-ns "namespace"
535 <td>\ref api-tir-stream-cls-prop-name "Name"
538 <td>\bt_mip version 1: \ref api-tir-stream-cls-prop-uid "UID"
541 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
544 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
547 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
550 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
553 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
556 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
559 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
562 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
565 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
568 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
571 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
574 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
577 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
578 <td>Empty \bt_map_val
581 @param[in] trace_class
582 Trace class to add the created stream class to.
585 New stream class reference, or \c NULL on memory error.
587 @bt_pre_not_null{trace_class}
589 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
592 @bt_post_success_frozen{trace_class}
594 @sa bt_stream_class_create_with_id() —
595 Creates a stream class with a specific numeric ID and adds it to a
598 extern bt_stream_class
*bt_stream_class_create(
599 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
603 Creates a default stream class with the numeric ID \bt_p{id} and adds
604 it to the \bt_trace_cls \bt_p{trace_class}.
608 Only use this function if
611 bt_trace_class_assigns_automatic_stream_class_id(trace_class)
616 Otherwise, use bt_stream_class_create().
619 On success, the returned stream class has the following property values:
626 <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
629 <td>\bt_mip version 1: \ref api-tir-stream-cls-prop-ns "namespace"
632 <td>\ref api-tir-stream-cls-prop-name "Name"
635 <td>\bt_mip version 1: \ref api-tir-stream-cls-prop-uid "UID"
638 <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
641 <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
644 <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
647 <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
650 <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
653 <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
656 <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
659 <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
662 <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
665 <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
668 <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
671 <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
674 <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
675 <td>Empty \bt_map_val
678 @param[in] trace_class
679 Trace class to add the created stream class to.
681 Numeric ID of the stream class to create and add to
685 New stream class reference, or \c NULL on memory error.
687 @bt_pre_not_null{trace_class}
689 <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
692 \bt_p{trace_class} does not contain a stream class with the numeric
695 @bt_post_success_frozen{trace_class}
697 @sa bt_stream_class_create() —
698 Creates a stream class with an automatic numeric ID and adds it to a
701 extern bt_stream_class
*bt_stream_class_create_with_id(
702 bt_trace_class
*trace_class
, uint64_t id
) __BT_NOEXCEPT
;
707 @name Trace class access
713 Borrows the \bt_trace_cls which contains the stream class
716 @param[in] stream_class
717 Stream class from which to borrow the trace class which contains it.
720 Trace class which contains \bt_p{stream_class}.
722 @bt_pre_not_null{stream_class}
724 @sa bt_stream_class_borrow_trace_class_const() —
725 \c const version of this function.
727 extern bt_trace_class
*bt_stream_class_borrow_trace_class(
728 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
732 Borrows the \bt_trace_cls which contains the stream class
733 \bt_p{stream_class} (\c const version).
735 See bt_stream_class_borrow_trace_class().
737 extern const bt_trace_class
*bt_stream_class_borrow_trace_class_const(
738 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
743 @name Event class access
749 Returns the number of \bt_p_ev_cls contained in the stream
750 class \bt_p{stream_class}.
752 @param[in] stream_class
753 Stream class of which to get the number of contained event classes.
756 Number of contained event classes in \bt_p{stream_class}.
758 @bt_pre_not_null{stream_class}
760 extern uint64_t bt_stream_class_get_event_class_count(
761 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
765 Borrows the \bt_ev_cls at index \bt_p{index} from the
766 stream class \bt_p{stream_class}.
768 @param[in] stream_class
769 Stream class from which to borrow the event class at index
772 Index of the event class to borrow from \bt_p{stream_class}.
776 \em Borrowed reference of the event class of
777 \bt_p{stream_class} at index \bt_p{index}.
779 The returned pointer remains valid as long as \bt_p{stream_class}
783 @bt_pre_not_null{stream_class}
785 \bt_p{index} is less than the number of event classes in
786 \bt_p{stream_class} (as returned by
787 bt_stream_class_get_event_class_count()).
789 @sa bt_stream_class_get_event_class_count() —
790 Returns the number of event classes contained in a stream class.
791 @sa bt_stream_class_borrow_event_class_by_index_const() —
792 \c const version of this function.
794 extern bt_event_class
*
795 bt_stream_class_borrow_event_class_by_index(
796 bt_stream_class
*stream_class
, uint64_t index
) __BT_NOEXCEPT
;
800 Borrows the \bt_ev_cls at index \bt_p{index} from the
801 stream class \bt_p{stream_class} (\c const version).
803 See bt_stream_class_borrow_event_class_by_index().
805 extern const bt_event_class
*
806 bt_stream_class_borrow_event_class_by_index_const(
807 const bt_stream_class
*stream_class
, uint64_t index
)
812 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
813 stream class \bt_p{stream_class}.
815 If there's no event class having the numeric ID \bt_p{id} in
816 \bt_p{stream_class}, this function returns \c NULL.
818 @param[in] stream_class
819 Stream class from which to borrow the event class having the
820 numeric ID \bt_p{id}.
822 ID of the event class to borrow from \bt_p{stream_class}.
826 \em Borrowed reference of the event class of
827 \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL
830 The returned pointer remains valid as long as \bt_p{stream_class}
834 @bt_pre_not_null{stream_class}
836 @sa bt_stream_class_borrow_event_class_by_id_const() —
837 \c const version of this function.
839 extern bt_event_class
*
840 bt_stream_class_borrow_event_class_by_id(
841 bt_stream_class
*stream_class
, uint64_t id
) __BT_NOEXCEPT
;
845 Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
846 stream class \bt_p{stream_class} (\c const version).
848 See bt_stream_class_borrow_event_class_by_id().
850 extern const bt_event_class
*
851 bt_stream_class_borrow_event_class_by_id_const(
852 const bt_stream_class
*stream_class
, uint64_t id
) __BT_NOEXCEPT
;
863 Returns the numeric ID of the stream class \bt_p{stream_class}.
865 See the \ref api-tir-stream-cls-prop-id "numeric ID" property.
867 @param[in] stream_class
868 Stream class of which to get the numeric ID.
871 Numeric ID of \bt_p{stream_class}.
873 @bt_pre_not_null{stream_class}
875 @sa bt_stream_class_create_with_id() —
876 Creates a stream class with a specific numeric ID and adds it to a
879 extern uint64_t bt_stream_class_get_id(
880 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
884 Status codes for bt_stream_class_set_namespace().
886 typedef enum bt_stream_class_set_namespace_status
{
891 BT_STREAM_CLASS_SET_NAMESPACE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
897 BT_STREAM_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
898 } bt_stream_class_set_namespace_status
;
902 Sets the namespace of the stream class \bt_p{stream_class} to
905 See the \ref api-tir-stream-cls-prop-ns "namespace" property.
907 @param[in] stream_class
908 Stream class of which to set the namespace to \bt_p{ns}.
910 New namespace of \bt_p{stream_class} (copied).
912 @retval #BT_STREAM_CLASS_SET_NAMESPACE_STATUS_OK
914 @retval #BT_STREAM_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR
917 @bt_pre_not_null{stream_class}
918 @bt_pre_hot{stream_class}
919 @bt_pre_stream_cls_with_mip{stream_class, 1}
922 @sa bt_stream_class_get_namespace() —
923 Returns the namespace of a stream class.
925 extern bt_stream_class_set_namespace_status
bt_stream_class_set_namespace(
926 bt_stream_class
*stream_class
, const char *ns
) __BT_NOEXCEPT
;
930 Returns the namespace of the stream class \bt_p{stream_class}.
932 See the \ref api-tir-stream-cls-prop-ns "namespace" property.
934 If \bt_p{stream_class} has no namespace, this function returns \c NULL.
936 @param[in] stream_class
937 Stream class of which to get the namespace.
941 Namespace of \bt_p{stream_class}, or \c NULL if none.
943 The returned pointer remains valid as long as \bt_p{stream_class}
947 @bt_pre_not_null{stream_class}
948 @bt_pre_stream_cls_with_mip{stream_class, 1}
950 @sa bt_stream_class_set_namespace() —
951 Sets the namespace of a stream class.
953 extern const char *bt_stream_class_get_namespace(
954 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
958 Status codes for bt_stream_class_set_name().
960 typedef enum bt_stream_class_set_name_status
{
965 BT_STREAM_CLASS_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
971 BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
972 } bt_stream_class_set_name_status
;
976 Sets the name of the stream class \bt_p{stream_class} to
977 a copy of \bt_p{name}.
979 See the \ref api-tir-stream-cls-prop-name "name" property.
981 @param[in] stream_class
982 Stream class of which to set the name to \bt_p{name}.
984 New name of \bt_p{stream_class} (copied).
986 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
988 @retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
991 @bt_pre_not_null{stream_class}
992 @bt_pre_hot{stream_class}
993 @bt_pre_not_null{name}
995 @sa bt_stream_class_get_name() —
996 Returns the name of a stream class.
998 extern bt_stream_class_set_name_status
bt_stream_class_set_name(
999 bt_stream_class
*stream_class
, const char *name
) __BT_NOEXCEPT
;
1003 Returns the name of the stream class \bt_p{stream_class}.
1005 See the \ref api-tir-stream-cls-prop-name "name" property.
1007 If \bt_p{stream_class} has no name, this function returns \c NULL.
1009 @param[in] stream_class
1010 Stream class of which to get the name.
1014 Name of \bt_p{stream_class}, or \c NULL if none.
1016 The returned pointer remains valid as long as \bt_p{stream_class}
1020 @bt_pre_not_null{stream_class}
1022 @sa bt_stream_class_set_name() —
1023 Sets the name of a stream class.
1025 extern const char *bt_stream_class_get_name(
1026 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1030 Status codes for bt_stream_class_set_uid().
1032 typedef enum bt_stream_class_set_uid_status
{
1037 BT_STREAM_CLASS_SET_UID_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1043 BT_STREAM_CLASS_SET_UID_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1044 } bt_stream_class_set_uid_status
;
1049 <a href="https://en.wikipedia.org/wiki/Unique_identifier">unique identifier</a> (UID)
1050 of the stream class \bt_p{stream_class} to
1051 a copy of \bt_p{uid}.
1053 See the \ref api-tir-stream-cls-prop-uid "UID" property.
1055 @param[in] stream_class
1056 Stream class of which to set the UID to \bt_p{uid}.
1058 New UID of \bt_p{stream_class} (copied).
1060 @retval #BT_STREAM_CLASS_SET_UID_STATUS_OK
1062 @retval #BT_STREAM_CLASS_SET_UID_STATUS_MEMORY_ERROR
1065 @bt_pre_not_null{stream_class}
1066 @bt_pre_hot{stream_class}
1067 @bt_pre_stream_cls_with_mip{stream_class, 1}
1068 @bt_pre_not_null{uid}
1070 @sa bt_stream_class_get_uid() —
1071 Returns the UID of a stream class.
1073 extern bt_stream_class_set_uid_status
bt_stream_class_set_uid(
1074 bt_stream_class
*stream_class
, const char *uid
) __BT_NOEXCEPT
;
1078 Returns the UID of the stream class \bt_p{stream_class}.
1080 See the \ref api-tir-stream-cls-prop-uid "UID" property.
1082 If \bt_p{stream_class} has no UID, this function returns \c NULL.
1084 @param[in] stream_class
1085 Stream class of which to get the UID.
1089 UID of \bt_p{stream_class}, or \c NULL if none.
1091 The returned pointer remains valid as long as \bt_p{stream_class}
1095 @bt_pre_not_null{stream_class}
1096 @bt_pre_stream_cls_with_mip{stream_class, 1}
1098 @sa bt_stream_class_set_uid() —
1099 Sets the UID of a stream class.
1101 extern const char *bt_stream_class_get_uid(
1102 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1106 Status codes for bt_stream_class_set_default_clock_class().
1108 typedef enum bt_stream_class_set_default_clock_class_status
{
1113 BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1114 } bt_stream_class_set_default_clock_class_status
;
1118 Sets the default \bt_clock_cls of the stream class
1119 \bt_p{stream_class} to \bt_p{clock_class}.
1121 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1124 @param[in] stream_class
1125 Stream class of which to set the default clock class to
1127 @param[in] clock_class
1128 New default clock class of \bt_p{stream_class}.
1130 @retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
1133 @bt_pre_not_null{stream_class}
1134 @bt_pre_hot{stream_class}
1135 @bt_pre_not_null{clock_class}
1137 @sa bt_stream_class_borrow_default_clock_class() —
1138 Borrows the default clock class of a stream class.
1139 @sa bt_stream_class_borrow_default_clock_class_const() —
1140 Borrows the default clock class of a stream class (\c const version).
1142 extern bt_stream_class_set_default_clock_class_status
1143 bt_stream_class_set_default_clock_class(
1144 bt_stream_class
*stream_class
,
1145 bt_clock_class
*clock_class
) __BT_NOEXCEPT
;
1149 Borrows the default \bt_clock_cls from the stream class
1150 \bt_p{stream_class}.
1152 See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
1155 If \bt_p{stream_class} has no default clock class, this function
1158 @param[in] stream_class
1159 Stream class from which to borrow the default clock class.
1162 \em Borrowed reference of the default clock class of
1163 \bt_p{stream_class}, or \c NULL if none.
1165 @bt_pre_not_null{stream_class}
1167 @sa bt_stream_class_set_default_clock_class() —
1168 Sets the default clock class of a stream class.
1169 @sa bt_stream_class_borrow_default_clock_class_const() —
1170 \c const version of this function.
1172 extern bt_clock_class
*bt_stream_class_borrow_default_clock_class(
1173 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1177 Borrows the default \bt_clock_cls from the stream class
1178 \bt_p{stream_class} (\c const version).
1180 See bt_stream_class_borrow_default_clock_class().
1182 extern const bt_clock_class
*
1183 bt_stream_class_borrow_default_clock_class_const(
1184 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1188 Status codes for bt_stream_class_set_packet_context_field_class()
1189 and bt_stream_class_set_event_common_context_field_class().
1191 typedef enum bt_stream_class_set_field_class_status
{
1196 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1202 BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1203 } bt_stream_class_set_field_class_status
;
1207 Sets the packet context \bt_fc of the stream class
1208 \bt_p{stream_class} to \bt_p{field_class}.
1210 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1213 \bt_p{stream_class} must support packets (see
1214 bt_stream_class_set_supports_packets()).
1216 @param[in] stream_class
1217 Stream class of which to set the packet context field class to
1219 @param[in] field_class
1220 New packet context field class of \bt_p{stream_class}.
1222 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1224 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1227 @bt_pre_not_null{stream_class}
1228 @bt_pre_hot{stream_class}
1230 <code>bt_stream_class_supports_packets(stream_class)</code>
1232 @bt_pre_not_null{field_class}
1233 @bt_pre_is_struct_fc{field_class}
1235 \bt_p{field_class}, or any of its contained field classes,
1236 is not already part of a stream class or of an \bt_ev_cls.
1238 If any of the field classes recursively contained in
1239 \bt_p{field_class} has a
1240 \ref api-tir-fc-link "link to another field class", it must honor
1241 the field class link rules.
1243 If any of the field classes recursively contained in
1244 \bt_p{field_class} has a
1245 \ref api-tir-fc-link "link to another field class", it must honor
1246 the field class link rules.
1248 @bt_post_success_frozen{field_class}
1250 @sa bt_stream_class_borrow_packet_context_field_class() —
1251 Borrows the packet context field class of a stream class.
1252 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1253 Borrows the packet context field class of a stream class
1256 extern bt_stream_class_set_field_class_status
1257 bt_stream_class_set_packet_context_field_class(
1258 bt_stream_class
*stream_class
,
1259 bt_field_class
*field_class
) __BT_NOEXCEPT
;
1263 Borrows the packet context \bt_fc from the stream class
1264 \bt_p{stream_class}.
1266 See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
1269 If \bt_p{stream_class} has no packet context field class, this function
1272 @param[in] stream_class
1273 Stream class from which to borrow the packet context field class.
1276 \em Borrowed reference of the packet context field class of
1277 \bt_p{stream_class}, or \c NULL if none.
1279 @bt_pre_not_null{stream_class}
1281 @sa bt_stream_class_set_packet_context_field_class() —
1282 Sets the packet context field class of a stream class.
1283 @sa bt_stream_class_borrow_packet_context_field_class_const() —
1284 \c const version of this function.
1286 extern bt_field_class
*
1287 bt_stream_class_borrow_packet_context_field_class(
1288 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1292 Borrows the packet context \bt_fc from the stream class
1293 \bt_p{stream_class} (\c const version).
1295 See bt_stream_class_borrow_packet_context_field_class().
1297 extern const bt_field_class
*
1298 bt_stream_class_borrow_packet_context_field_class_const(
1299 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1303 Sets the event common context \bt_fc of the stream class
1304 \bt_p{stream_class} to \bt_p{field_class}.
1306 See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class"
1309 @param[in] stream_class
1310 Stream class of which to set the event common context field class to
1312 @param[in] field_class
1313 New event common context field class of \bt_p{stream_class}.
1315 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
1317 @retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
1320 @bt_pre_not_null{stream_class}
1321 @bt_pre_hot{stream_class}
1322 @bt_pre_not_null{field_class}
1323 @bt_pre_is_struct_fc{field_class}
1325 \bt_p{field_class}, or any of its contained field classes,
1326 is not already part of a stream class or of an \bt_ev_cls.
1328 If any of the field classes recursively contained in
1329 \bt_p{field_class} has a
1330 \ref api-tir-fc-link "link to another field class", it must honor
1331 the field class link rules.
1333 @bt_post_success_frozen{field_class}
1335 @sa bt_stream_class_borrow_event_common_context_field_class() —
1336 Borrows the event common context field class of a stream class.
1337 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1338 Borrows the event common context field class of a stream class
1341 extern bt_stream_class_set_field_class_status
1342 bt_stream_class_set_event_common_context_field_class(
1343 bt_stream_class
*stream_class
,
1344 bt_field_class
*field_class
) __BT_NOEXCEPT
;
1348 Borrows the event common context \bt_fc from the stream class
1349 \bt_p{stream_class}.
1351 See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class"
1354 If \bt_p{stream_class} has no event common context field class, this
1355 function returns \c NULL.
1357 @param[in] stream_class
1358 Stream class from which to borrow the event common context
1362 \em Borrowed reference of the event common context field class of
1363 \bt_p{stream_class}, or \c NULL if none.
1365 @bt_pre_not_null{stream_class}
1367 @sa bt_stream_class_set_event_common_context_field_class() —
1368 Sets the event common context field class of a stream class.
1369 @sa bt_stream_class_borrow_event_common_context_field_class_const() —
1370 \c const version of this function.
1373 extern bt_field_class
*
1374 bt_stream_class_borrow_event_common_context_field_class(
1375 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1379 Borrows the event common context \bt_fc from the stream class
1380 \bt_p{stream_class} (\c const version()).
1382 See bt_stream_class_borrow_event_common_context_field_class().
1384 extern const bt_field_class
*
1385 bt_stream_class_borrow_event_common_context_field_class_const(
1386 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1390 Sets whether or not the stream class \bt_p{stream_class}
1391 automatically assigns a numeric ID to an \bt_ev_cls you create and
1394 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1397 @param[in] stream_class
1398 Stream class of which to set whether or not it assigns automatic
1400 @param[in] assigns_automatic_event_class_id
1401 #BT_TRUE to make \bt_p{stream_class} assign automatic event class
1404 @bt_pre_not_null{stream_class}
1405 @bt_pre_hot{stream_class}
1407 @sa bt_stream_class_assigns_automatic_event_class_id() —
1408 Returns whether or not a stream class automatically assigns
1411 extern void bt_stream_class_set_assigns_automatic_event_class_id(
1412 bt_stream_class
*stream_class
,
1413 bt_bool assigns_automatic_event_class_id
) __BT_NOEXCEPT
;
1417 Returns whether or not the stream class \bt_p{stream_class}
1418 automatically assigns a numeric ID to an \bt_ev_cls you create
1421 See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
1424 @param[in] stream_class
1425 Stream class of which to get whether or not it assigns automatic
1429 #BT_TRUE if \bt_p{stream_class} automatically
1430 assigns event class IDs.
1432 @bt_pre_not_null{stream_class}
1434 @sa bt_stream_class_set_assigns_automatic_event_class_id() —
1435 Sets whether or not a stream class automatically assigns
1438 extern bt_bool
bt_stream_class_assigns_automatic_event_class_id(
1439 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1443 Sets whether or not the stream class \bt_p{stream_class}
1444 automatically assigns a numeric ID to a \bt_stream you create from
1447 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1450 @param[in] stream_class
1451 Stream class of which to set whether or not it assigns automatic
1453 @param[in] assigns_automatic_stream_id
1454 #BT_TRUE to make \bt_p{stream_class} assign automatic stream
1457 @bt_pre_not_null{stream_class}
1458 @bt_pre_hot{stream_class}
1460 @sa bt_stream_class_assigns_automatic_stream_id() —
1461 Returns whether or not a stream class automatically assigns
1464 extern void bt_stream_class_set_assigns_automatic_stream_id(
1465 bt_stream_class
*stream_class
,
1466 bt_bool assigns_automatic_stream_id
) __BT_NOEXCEPT
;
1470 Returns whether or not the stream class \bt_p{stream_class}
1471 automatically assigns a numeric ID to a \bt_stream you create
1474 See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
1477 @param[in] stream_class
1478 Stream class of which to get whether or not it assigns automatic
1482 #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs.
1484 @bt_pre_not_null{stream_class}
1486 @sa bt_stream_class_set_assigns_automatic_stream_id() —
1487 Sets whether or not a stream class automatically assigns
1490 extern bt_bool
bt_stream_class_assigns_automatic_stream_id(
1491 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1495 Sets whether or not the instances (\bt_p_stream) of the
1496 stream class \bt_p{stream_class} have \bt_p_pkt and, if so,
1497 if those packets have beginning and/or end default
1501 \ref api-tir-stream-cls-prop-supports-pkt "supports packets?",
1502 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?",
1504 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1507 @param[in] stream_class
1508 Stream class of which to set whether or not its streams have
1510 @param[in] supports_packets
1511 #BT_TRUE to make the streams of \bt_p{stream_class} have packets.
1512 @param[in] with_beginning_default_clock_snapshot
1513 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1514 have a beginning default clock snapshot.
1515 @param[in] with_end_default_clock_snapshot
1516 #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
1517 have an end default clock snapshot.
1519 @bt_pre_not_null{stream_class}
1520 @bt_pre_hot{stream_class}
1522 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1524 \bt_p{supports_packets} is also #BT_TRUE.
1526 <strong>If \bt_p{with_beginning_default_clock_snapshot} is
1528 \bt_p{supports_packets} is also #BT_TRUE.
1530 <strong>If \bt_p{with_beginning_default_clock_snapshot} or
1531 \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
1532 \bt_p{stream_class} has a
1533 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1535 @sa bt_stream_class_supports_packets() —
1536 Returns whether or not a stream class's streams have packets.
1537 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1538 Returns whether or not the packets of a stream class's streams
1539 have a beginning default clock snapshot.
1540 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1541 Returns whether or not the packets of a stream class's streams
1542 have an end default clock snapshot.
1544 extern void bt_stream_class_set_supports_packets(
1545 bt_stream_class
*stream_class
, bt_bool supports_packets
,
1546 bt_bool with_beginning_default_clock_snapshot
,
1547 bt_bool with_end_default_clock_snapshot
) __BT_NOEXCEPT
;
1551 Returns whether or not the instances (\bt_p_stream) of the
1552 stream class \bt_p{stream_class} have \bt_p_pkt.
1554 See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?"
1557 @param[in] stream_class
1558 Stream class of which to get whether or not its streams have
1562 #BT_TRUE if the streams of \bt_p{stream_class} have packets.
1564 @bt_pre_not_null{stream_class}
1566 @sa bt_stream_class_set_supports_packets() —
1567 Sets whether or not a stream class's streams have packets.
1569 extern bt_bool
bt_stream_class_supports_packets(
1570 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1574 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1575 of the stream class \bt_p{stream_class} have a beginning
1579 \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?"
1582 @param[in] stream_class
1583 Stream class of which to get whether or not its streams's packets
1584 have a beginning default clock snapshot.
1587 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a
1588 beginning default clock snapshot.
1590 @bt_pre_not_null{stream_class}
1592 @sa bt_stream_class_set_supports_packets() —
1593 Sets whether or not a stream class's streams have packets.
1594 @sa bt_stream_class_packets_have_end_default_clock_snapshot() —
1595 Returns whether or not the packets of a stream class's streams
1596 have an end default clock snapshot.
1598 extern bt_bool
bt_stream_class_packets_have_beginning_default_clock_snapshot(
1599 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1603 Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
1604 of the stream class \bt_p{stream_class} have an end
1608 \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
1611 @param[in] stream_class
1612 Stream class of which to get whether or not its streams's packets
1613 have an end default clock snapshot.
1616 #BT_TRUE if the packets of the streams of \bt_p{stream_class} have
1617 an end default clock snapshot.
1619 @bt_pre_not_null{stream_class}
1621 @sa bt_stream_class_set_supports_packets() —
1622 Sets whether or not a stream class's streams have packets.
1623 @sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
1624 Returns whether or not the packets of a stream class's streams
1625 have a beginning default clock snapshot.
1627 extern bt_bool
bt_stream_class_packets_have_end_default_clock_snapshot(
1628 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1632 Sets whether or not the instances (\bt_p_stream) of the
1633 stream class \bt_p{stream_class} can have discarded events and,
1634 if so, if the \bt_p_disc_ev_msg of those streams have
1635 beginning and end default \bt_p_cs.
1638 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1640 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1643 @param[in] stream_class
1644 Stream class of which to set whether or not its streams can have
1646 @param[in] supports_discarded_events
1647 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1648 have discarded events.
1649 @param[in] with_default_clock_snapshots
1650 #BT_TRUE to make the discarded events messages the streams of
1651 \bt_p{stream_class} have beginning and end default clock snapshots.
1653 @bt_pre_not_null{stream_class}
1654 @bt_pre_hot{stream_class}
1656 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1657 \bt_p{supports_discarded_events} is also #BT_TRUE.
1659 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1660 \bt_p{stream_class} has a
1661 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1663 @sa bt_stream_class_supports_discarded_events() —
1664 Returns whether or not a stream class's streams can have
1666 @sa bt_stream_class_discarded_events_have_default_clock_snapshots() —
1667 Returns whether or not the discarded events messages of a
1668 stream class's streams have beginning and end default clock
1671 extern void bt_stream_class_set_supports_discarded_events(
1672 bt_stream_class
*stream_class
,
1673 bt_bool supports_discarded_events
,
1674 bt_bool with_default_clock_snapshots
) __BT_NOEXCEPT
;
1678 Returns whether or not the instances (\bt_p_stream) of the
1679 stream class \bt_p{stream_class} can have discarded events.
1682 \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
1685 @param[in] stream_class
1686 Stream class of which to get whether or not its streams can have
1690 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1693 @bt_pre_not_null{stream_class}
1695 @sa bt_stream_class_set_supports_discarded_events() —
1696 Sets whether or not a stream class's streams can have discarded
1699 extern bt_bool
bt_stream_class_supports_discarded_events(
1700 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1704 Returns whether or not the \bt_p_disc_ev_msg of the instances
1705 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1706 beginning and end default \bt_p_cs.
1709 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
1712 @param[in] stream_class
1713 Stream class of which to get whether or not its streams's discarded
1714 events messages have a beginning and end default clock snapshots.
1717 #BT_TRUE if the discarded events messages of the streams of
1718 \bt_p{stream_class} have beginning and end default clock snapshots.
1720 @bt_pre_not_null{stream_class}
1722 @sa bt_stream_class_set_supports_discarded_events() —
1723 Sets whether or not a stream class's streams can have discarded
1726 extern bt_bool
bt_stream_class_discarded_events_have_default_clock_snapshots(
1727 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1731 Sets whether or not the instances (\bt_p_stream) of the
1732 stream class \bt_p{stream_class} can have discarded packets and,
1733 if so, if the \bt_p_disc_pkt_msg of those streams have
1734 beginning and end default \bt_p_cs.
1737 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1739 \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?"
1742 \bt_p{stream_class} must support packets (see
1743 bt_stream_class_set_supports_packets()).
1745 @param[in] stream_class
1746 Stream class of which to set whether or not its streams can have
1748 @param[in] supports_discarded_packets
1749 #BT_TRUE to make the streams of \bt_p{stream_class} be able to
1750 have discarded packets.
1751 @param[in] with_default_clock_snapshots
1752 #BT_TRUE to make the discarded packets messages the streams of
1753 \bt_p{stream_class} have beginning and end default clock snapshots.
1755 @bt_pre_not_null{stream_class}
1756 @bt_pre_hot{stream_class}
1758 <code>bt_stream_class_supports_packets(stream_class)</code>
1761 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1762 \bt_p{supports_discarded_packets} is also #BT_TRUE.
1764 <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
1765 \bt_p{stream_class} has a
1766 \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
1768 @sa bt_stream_class_supports_discarded_packets() —
1769 Returns whether or not a stream class's streams can have
1771 @sa bt_stream_class_discarded_packets_have_default_clock_snapshots() —
1772 Returns whether or not the discarded packets messages of a
1773 stream class's streams have beginning and end default clock
1776 extern void bt_stream_class_set_supports_discarded_packets(
1777 bt_stream_class
*stream_class
,
1778 bt_bool supports_discarded_packets
,
1779 bt_bool with_default_clock_snapshots
) __BT_NOEXCEPT
;
1783 Returns whether or not the instances (\bt_p_stream) of the
1784 stream class \bt_p{stream_class} can have discarded packets.
1787 \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
1790 @param[in] stream_class
1791 Stream class of which to get whether or not its streams can have
1795 #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
1798 @bt_pre_not_null{stream_class}
1800 @sa bt_stream_class_set_supports_discarded_packets() —
1801 Sets whether or not a stream class's streams can have discarded
1804 extern bt_bool
bt_stream_class_supports_discarded_packets(
1805 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1809 Returns whether or not the \bt_p_disc_pkt_msg of the instances
1810 (\bt_p_stream) of the stream class \bt_p{stream_class} have
1811 beginning and end default \bt_p_cs.
1814 \ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?"
1817 @param[in] stream_class
1818 Stream class of which to get whether or not its streams's discarded
1819 packets messages have a beginning and end default clock snapshots.
1822 #BT_TRUE if the discarded packets messages of the streams of
1823 \bt_p{stream_class} have beginning and end default clock snapshots.
1825 @bt_pre_not_null{stream_class}
1827 @sa bt_stream_class_set_supports_discarded_packets() —
1828 Sets whether or not a stream class's streams can have discarded
1831 extern bt_bool
bt_stream_class_discarded_packets_have_default_clock_snapshots(
1832 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1836 Sets the user attributes of the stream class \bt_p{stream_class} to
1837 \bt_p{user_attributes}.
1839 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1843 When you create a default stream class with bt_stream_class_create()
1844 or bt_stream_class_create_with_id(), the stream class's initial user
1845 attributes is an empty \bt_map_val. Therefore you can borrow it with
1846 bt_stream_class_borrow_user_attributes() and fill it directly
1847 instead of setting a new one with this function.
1849 @param[in] stream_class
1850 Stream class of which to set the user attributes to
1851 \bt_p{user_attributes}.
1852 @param[in] user_attributes
1853 New user attributes of \bt_p{stream_class}.
1855 @bt_pre_not_null{stream_class}
1856 @bt_pre_hot{stream_class}
1857 @bt_pre_not_null{user_attributes}
1858 @bt_pre_is_map_val{user_attributes}
1860 @sa bt_stream_class_borrow_user_attributes() —
1861 Borrows the user attributes of a stream class.
1863 extern void bt_stream_class_set_user_attributes(
1864 bt_stream_class
*stream_class
,
1865 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
1869 Borrows the user attributes of the stream class \bt_p{stream_class}.
1871 See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
1875 When you create a default stream class with bt_stream_class_create()
1876 or bt_stream_class_create_with_id(), the stream class's initial user
1877 attributes is an empty \bt_map_val.
1879 @param[in] stream_class
1880 Stream class from which to borrow the user attributes.
1883 User attributes of \bt_p{stream_class} (a \bt_map_val).
1885 @bt_pre_not_null{stream_class}
1887 @sa bt_stream_class_set_user_attributes() —
1888 Sets the user attributes of a stream class.
1889 @sa bt_stream_class_borrow_user_attributes_const() —
1890 \c const version of this function.
1892 extern bt_value
*bt_stream_class_borrow_user_attributes(
1893 bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1897 Borrows the user attributes of the stream class \bt_p{stream_class}
1900 See bt_stream_class_borrow_user_attributes().
1902 extern const bt_value
*bt_stream_class_borrow_user_attributes_const(
1903 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1908 @name Reference count
1914 Increments the \ref api-fund-shared-object "reference count" of
1915 the stream class \bt_p{stream_class}.
1917 @param[in] stream_class
1919 Stream class of which to increment the reference count.
1924 @sa bt_stream_class_put_ref() —
1925 Decrements the reference count of a stream class.
1927 extern void bt_stream_class_get_ref(
1928 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1932 Decrements the \ref api-fund-shared-object "reference count" of
1933 the stream class \bt_p{stream_class}.
1935 @param[in] stream_class
1937 Stream class of which to decrement the reference count.
1942 @sa bt_stream_class_get_ref() —
1943 Increments the reference count of a stream class.
1945 extern void bt_stream_class_put_ref(
1946 const bt_stream_class
*stream_class
) __BT_NOEXCEPT
;
1950 Decrements the reference count of the stream class
1951 \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL.
1953 @param _stream_class
1955 Stream class of which to decrement the reference count.
1957 Can contain \c NULL.
1960 @bt_pre_assign_expr{_stream_class}
1962 #define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \
1964 bt_stream_class_put_ref(_stream_class); \
1965 (_stream_class) = NULL; \
1970 Decrements the reference count of the stream class \bt_p{_dst}, sets
1971 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1973 This macro effectively moves a stream class reference from the expression
1974 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1975 \bt_p{_dst} reference.
1979 Destination expression.
1981 Can contain \c NULL.
1987 Can contain \c NULL.
1990 @bt_pre_assign_expr{_dst}
1991 @bt_pre_assign_expr{_src}
1993 #define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \
1995 bt_stream_class_put_ref(_dst); \
2008 #endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_H */