X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Ftrace-ir%2Fstream-class.h;h=d05d47358e66201d27a5f8b6bdbd66dc7da31185;hp=58bdbdc49cfd3e631715845d1b0bc6cffc2b4fee;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/include/babeltrace2/trace-ir/stream-class.h b/include/babeltrace2/trace-ir/stream-class.h index 58bdbdc4..d05d4735 100644 --- a/include/babeltrace2/trace-ir/stream-class.h +++ b/include/babeltrace2/trace-ir/stream-class.h @@ -35,92 +35,1789 @@ extern "C" { #endif +/*! +@defgroup api-tir-stream-cls Stream class +@ingroup api-tir + +@brief + Class of \bt_p_stream. + +A stream class is the class of \bt_p_stream: + +@image html trace-structure.png + +In the illustration above, notice that: + +- A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages". + + The sequence always starts with a \bt_sb_msg and ends with a + \bt_se_msg. + +- A stream is an instance of a stream class. + +A stream class is a \ref api-tir "trace IR" metadata object. + +A stream class is a \ref api-fund-shared-object "shared object": get a +new reference with bt_stream_class_get_ref() and put an existing +reference with bt_stream_class_put_ref(). + +Some library functions \ref api-fund-freezing "freeze" stream classes on +success. The documentation of those functions indicate this +postcondition. You can still create and add an \bt_p_ev_cls to a frozen +stream class with bt_event_class_create() or +bt_event_class_create_with_id(). + +The type of a stream class is #bt_stream_class. + +A \bt_trace_cls contains stream classes. All the stream classes of a +given trace class have unique +\ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class +which contains a stream class with bt_stream_class_borrow_trace_class() +or bt_stream_class_borrow_trace_class_const(). + +A stream class contains \bt_p_ev_cls. All the event classes of a given +stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get +the number of event classes in a stream class with +bt_stream_class_get_event_class_count(). Borrow a specific event class +from a stream class with bt_stream_class_borrow_event_class_by_index(), +bt_stream_class_borrow_event_class_by_index_const(), +bt_stream_class_borrow_event_class_by_id(), and +bt_stream_class_borrow_event_class_by_id_const(). + +A stream class controls what its instances (\bt_p_stream) support: + +
+
Default clock
+
+ By default, a stream class's streams do not have default clocks. + + Set the default \bt_clock_cls of a stream class with + bt_stream_class_set_default_clock_class(). This makes all its + streams have their own default clock. +
+ +
\anchor api-tir-stream-cls-pkt-support Packets
+
+ By default, a stream class's streams do not support \bt_p_pkt. + + In other words, you cannot create a packet for such a stream, + therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this + stream either. + + Enable packet support for a stream class's streams with + bt_stream_class_set_supports_packets(). + + bt_stream_class_set_supports_packets() also configures whether or + not the packets of the stream class's instances have beginning + and/or end default \bt_p_cs. +
+ +
Discarded events
+
+ By default, a stream class's streams do not support discarded + events. + + In other words, you cannot create \bt_p_disc_ev_msg for such a + stream. + + Enable discarded events support for a stream class's streams with + bt_stream_class_set_supports_discarded_events(). + + bt_stream_class_set_supports_discarded_events() also configures + whether or not the discarded events messages of the stream class's + instances have beginning and end default \bt_p_cs to indicate the + discarded events time range. +
+ +
Discarded packets
+
+ By default, a stream class's streams do not support discarded + packets. + + In other words, you cannot create \bt_p_disc_pkt_msg for such a + stream. + + Enable discarded packets support for a stream class's streams with + bt_stream_class_set_supports_discarded_packets(). This also implies + that you must enable packet support with + bt_stream_class_set_supports_packets(). + + bt_stream_class_set_supports_discarded_packets() also configures + whether or not the discarded packets messages of the stream class's + instances have beginning and end \bt_p_cs to indicate the + discarded packets time range. +
+
+ +Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a +stream class get automatic numeric IDs with +bt_stream_class_set_assigns_automatic_event_class_id() and +bt_stream_class_set_assigns_automatic_stream_id(). + +To create a default stream class: + +
+
+ If bt_trace_class_assigns_automatic_stream_class_id() returns + #BT_TRUE (the default) for the trace class to use +
+
Use bt_stream_class_create().
+ +
+ If bt_trace_class_assigns_automatic_stream_class_id() returns + #BT_FALSE for the trace class to use +
+
Use bt_stream_class_create_with_id().
+
+ +

Properties

+ +A stream class has the following properties: + +
+
\anchor api-tir-stream-cls-prop-id Numeric ID
+
+ Numeric ID, unique amongst the numeric IDs of the stream class's + \bt_trace_cls's stream classes. + + Depending on whether or not the stream class's trace class + automatically assigns \bt_ev_cls IDs + (see bt_trace_class_assigns_automatic_stream_class_id()), + set the stream class's numeric ID on creation with + bt_stream_class_create() or bt_stream_class_create_with_id(). + + You cannot change the numeric ID once the stream class is created. + + Get a stream class's numeric ID with bt_stream_class_get_id(). +
+ +
\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name
+
+ Name of the stream class. + + Use bt_stream_class_set_name() and bt_stream_class_get_name(). +
+ +
+ \anchor api-tir-stream-cls-prop-def-clock-cls + \bt_dt_opt Default clock class +
+
+ Default \bt_clock_cls of the stream class. + + As of \bt_name_version_min_maj, a stream class either has a default + clock class or none: it cannot have more than one clock class. + + When a stream class has a default clock class, then all its + instances (\bt_p_stream) have a default clock which is an instance + of the stream class's default clock class. + + Use bt_stream_class_set_default_clock_class(), + bt_stream_class_borrow_default_clock_class(), and + bt_stream_class_borrow_default_clock_class_const(). +
+ +
+ \anchor api-tir-stream-cls-prop-pc-fc + \bt_dt_opt Packet context field class +
+
+ \bt_c_pkt context \bt_fc of the stream class. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-pkt "supports packets". + + The context of a \bt_pkt contains data which is common to all the + packet's \bt_p_ev. + + Use bt_stream_class_set_packet_context_field_class() + bt_stream_class_borrow_packet_context_field_class(), + and bt_stream_class_borrow_packet_context_field_class_const(). +
+ +
+ \anchor api-tir-stream-cls-prop-ecc-fc + \bt_dt_opt Event common context field class +
+
+ \bt_c_ev common context \bt_fc of the stream class. + + The common context of an \bt_ev contains contextual data of which + the layout is common to all the stream class's \bt_p_ev_cls. + + Use bt_stream_class_set_event_common_context_field_class() + bt_stream_class_borrow_event_common_context_field_class(), + and bt_stream_class_borrow_event_common_context_field_class_const(). +
+ +
+ \anchor api-tir-stream-cls-prop-auto-ec-id + Assigns automatic event class IDs? +
+
+ Whether or not the \bt_p_ev_cls you create and add to the stream + class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically. + + Depending on the value of this property, to create an event class + and add it to the stream class: + +
+
#BT_TRUE
+
+ Use bt_event_class_create(). +
+ +
#BT_FALSE
+
+ Use bt_event_class_create_with_id(). +
+
+ + Use bt_stream_class_set_assigns_automatic_event_class_id() + and bt_stream_class_assigns_automatic_event_class_id(). +
+ +
+ \anchor api-tir-stream-cls-prop-auto-stream-id + Assigns automatic stream IDs? +
+
+ Whether or not the streams you create from the stream class + get \ref api-tir-stream-prop-id "numeric IDs" automatically. + + Depending on the value of this property, to create a stream + from the stream class: + +
+
#BT_TRUE
+
+ Use bt_stream_create(). +
+ +
#BT_FALSE
+
+ Use bt_stream_create_with_id(). +
+
+ + Use bt_stream_class_set_assigns_automatic_stream_id() + and bt_stream_class_assigns_automatic_stream_id(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-pkt + Supports packets? +
+
+ Whether or not the streams you create from the stream class + have \bt_p_pkt. + + If a stream has packets, then all the stream's \bt_p_ev are + conceptually contained within packets, which means you must + create \bt_p_ev_msg for such streams with + bt_message_event_create_with_packet() or + bt_message_event_create_with_packet_and_default_clock_snapshot() + instead of bt_message_event_create() or + bt_message_event_create_with_default_clock_snapshot(). + + It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to + indicate where packets begin and end within the stream's + \ref api-msg-seq "message sequence". + + Use bt_stream_class_set_supports_packets() and + bt_stream_class_supports_packets(). +
+ +
+ \anchor api-tir-stream-cls-prop-pkt-beg-cs + Packets have a beginning default clock snapshot? +
+
+ Whether or not the \bt_p_pkt of the streams you create from the + stream class have beginning default \bt_p_cs. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and + has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + + If the stream packets have a beginning default clock snapshot, then + you must create \bt_p_pb_msg with + bt_message_packet_beginning_create_with_default_clock_snapshot() + instead of bt_message_packet_beginning_create(). + + Use bt_stream_class_set_supports_packets() and + bt_stream_class_packets_have_beginning_default_clock_snapshot(). +
+ +
+ \anchor api-tir-stream-cls-prop-pkt-end-cs + Packets have an end default clock snapshot? +
+
+ Whether or not the \bt_p_pkt of the streams you create from the + stream class have end default \bt_p_cs. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and + has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + + If the stream packets have an end default clock snapshot, then you + must create \bt_p_pe_msg with + bt_message_packet_end_create_with_default_clock_snapshot() instead + of bt_message_packet_end_create(). + + Use bt_stream_class_set_supports_packets() and + bt_stream_class_packets_have_end_default_clock_snapshot(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-disc-ev + Supports discarded events? +
+
+ Whether or not the streams you create from the stream class can have + discarded events. + + If the stream class supports discarded events, then you can create + \bt_p_disc_ev_msg for this stream. + + Use bt_stream_class_set_supports_discarded_events() + and bt_stream_class_supports_discarded_events(). +
+ +
+ \anchor api-tir-stream-cls-prop-disc-ev-cs + Discarded events have default clock snapshots? +
+
+ Whether or not the stream's \bt_p_disc_ev_msg have + default beginning and end \bt_p_cs to indicate the discarded events + time range. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events" + and has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + + If the stream's discarded events messages have beginning and end + default clock snapshots, then you must create them with + bt_message_discarded_events_create_with_default_clock_snapshots() + instead of bt_message_discarded_events_create(). + + Use bt_stream_class_set_supports_discarded_events() + and bt_stream_class_discarded_events_have_default_clock_snapshots(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-disc-pkt + Supports discarded packets? +
+
+ Whether or not the streams you create from the stream class can have + discarded packets. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-pkt "supports packets". + + If the stream class supports discarded packets, then you can create + \bt_p_disc_pkt_msg for this stream. + + Use bt_stream_class_set_supports_discarded_packets() + and bt_stream_class_supports_discarded_packets(). +
+ +
+ \anchor api-tir-stream-cls-prop-disc-pkt-cs + Discarded packets have default clock snapshots? +
+
+ Whether or not the stream's \bt_p_disc_pkt_msg have + default beginning and end \bt_p_cs to indicate the discarded + packets time range. + + This property is only relevant if the stream class + \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets" + and has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + + If the stream's discarded packets messages have default clock + snapshots, then you must create them with + bt_message_discarded_packets_create_with_default_clock_snapshots() + instead of bt_message_discarded_packets_create(). + + Use bt_stream_class_set_supports_discarded_packets() + and bt_stream_class_discarded_packets_have_default_clock_snapshots(). +
+ +
+ \anchor api-tir-stream-cls-prop-user-attrs + \bt_dt_opt User attributes +
+
+ User attributes of the stream class. + + User attributes are custom attributes attached to a stream class. + + Use bt_stream_class_set_user_attributes(), + bt_stream_class_borrow_user_attributes(), and + bt_stream_class_borrow_user_attributes_const(). +
+
+*/ + +/*! @{ */ + +/*! +@name Type +@{ + +@typedef struct bt_stream_class bt_stream_class; + +@brief + Stream class. + +@} +*/ + +/*! +@name Creation +@{ +*/ + +/*! +@brief + Creates a default stream class and adds it to the \bt_trace_cls + \bt_p{trace_class}. + +@attention + @parblock + Only use this function if + + @code + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + @endcode + + returns #BT_TRUE. + + Otherwise, use bt_stream_class_create_with_id(). + @endparblock + +On success, the returned stream class has the following property values: + + + + + + + + + + + + + + + + + + +
Property + Value +
\ref api-tir-stream-cls-prop-id "Numeric ID" + Automatically assigned by \bt_p{trace_class} +
\ref api-tir-stream-cls-prop-name "Name" + \em None +
\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" + \em None +
\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" + \em None +
\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" + \em None +
\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" + Yes +
\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" + Yes +
\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" + No +
\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" + No +
\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" + No +
\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@param[in] trace_class + Trace class to add the created stream class to. + +@returns + New stream class reference, or \c NULL on memory error. + +@bt_pre_not_null{trace_class} +@pre + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + returns #BT_TRUE. + +@bt_post_success_frozen{trace_class} + +@sa bt_stream_class_create_with_id() — + Creates a stream class with a specific numeric ID and adds it to a + trace class. +*/ extern bt_stream_class *bt_stream_class_create( bt_trace_class *trace_class); +/*! +@brief + Creates a default stream class with the numeric ID \bt_p{id} and adds + it to the \bt_trace_cls \bt_p{trace_class}. + +@attention + @parblock + Only use this function if + + @code + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + @endcode + + returns #BT_FALSE. + + Otherwise, use bt_stream_class_create(). + @endparblock + +On success, the returned stream class has the following property values: + + + + + + + + + + + + + + + + + + +
Property + Value +
\ref api-tir-stream-cls-prop-id "Numeric ID" + \bt_p{id} +
\ref api-tir-stream-cls-prop-name "Name" + \em None +
\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" + \em None +
\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" + \em None +
\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" + \em None +
\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" + Yes +
\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" + Yes +
\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" + No +
\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" + No +
\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" + No +
\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@param[in] trace_class + Trace class to add the created stream class to. +@param[in] id + Numeric ID of the stream class to create and add to + \bt_p{trace_class}. + +@returns + New stream class reference, or \c NULL on memory error. + +@bt_pre_not_null{trace_class} +@pre + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + returns #BT_FALSE. +@pre + \bt_p{trace_class} does not contain a stream class with the numeric + ID \bt_p{id}. + +@bt_post_success_frozen{trace_class} + +@sa bt_stream_class_create() — + Creates a stream class with an automatic numeric ID and adds it to a + trace class. +*/ extern bt_stream_class *bt_stream_class_create_with_id( bt_trace_class *trace_class, uint64_t id); -extern bt_value *bt_stream_class_borrow_user_attributes( - bt_stream_class *stream_class); +/*! @} */ -extern void bt_stream_class_set_user_attributes( - bt_stream_class *stream_class, const bt_value *user_attributes); +/*! +@name Trace class access +@{ +*/ + +/*! +@brief + Borrows the \bt_trace_cls which contains the stream class + \bt_p{stream_class}. + +@param[in] stream_class + Stream class from which to borrow the trace class which contains it. +@returns + Trace class which contains \bt_p{stream_class}. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_borrow_trace_class_const() — + \c const version of this function. +*/ extern bt_trace_class *bt_stream_class_borrow_trace_class( bt_stream_class *stream_class); +/*! +@brief + Borrows the \bt_trace_cls which contains the stream class + \bt_p{stream_class} (\c const version). + +See bt_stream_class_borrow_trace_class(). +*/ +extern const bt_trace_class *bt_stream_class_borrow_trace_class_const( + const bt_stream_class *stream_class); + +/*! @} */ + +/*! +@name Event class access +@{ +*/ + +/*! +@brief + Returns the number of \bt_p_ev_cls contained in the stream + class \bt_p{stream_class}. + +@param[in] stream_class + Stream class of which to get the number of contained event classes. + +@returns + Number of contained event classes in \bt_p{stream_class}. + +@bt_pre_not_null{stream_class} +*/ +extern uint64_t bt_stream_class_get_event_class_count( + const bt_stream_class *stream_class); + +/*! +@brief + Borrows the \bt_ev_cls at index \bt_p{index} from the + stream class \bt_p{stream_class}. + +@param[in] stream_class + Stream class from which to borrow the event class at index + \bt_p{index}. +@param[in] index + Index of the event class to borrow from \bt_p{stream_class}. + +@returns + @parblock + \em Borrowed reference of the event class of + \bt_p{stream_class} at index \bt_p{index}. + + The returned pointer remains valid as long as \bt_p{stream_class} + exists. + @endparblock + +@bt_pre_not_null{stream_class} +@pre + \bt_p{index} is less than the number of event classes in + \bt_p{stream_class} (as returned by + bt_stream_class_get_event_class_count()). + +@sa bt_stream_class_get_event_class_count() — + Returns the number of event classes contained in a stream class. +@sa bt_stream_class_borrow_event_class_by_index_const() — + \c const version of this function. +*/ +extern bt_event_class * +bt_stream_class_borrow_event_class_by_index( + bt_stream_class *stream_class, uint64_t index); + +/*! +@brief + Borrows the \bt_ev_cls at index \bt_p{index} from the + stream class \bt_p{stream_class} (\c const version). + +See bt_stream_class_borrow_event_class_by_index(). +*/ +extern const bt_event_class * +bt_stream_class_borrow_event_class_by_index_const( + const bt_stream_class *stream_class, uint64_t index); + +/*! +@brief + Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the + stream class \bt_p{stream_class}. + +If there's no event class having the numeric ID \bt_p{id} in +\bt_p{stream_class}, this function returns \c NULL. + +@param[in] stream_class + Stream class from which to borrow the event class having the + numeric ID \bt_p{id}. +@param[in] id + ID of the event class to borrow from \bt_p{stream_class}. + +@returns + @parblock + \em Borrowed reference of the event class of + \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL + if none. + + The returned pointer remains valid as long as \bt_p{stream_class} + exists. + @endparblock + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_borrow_event_class_by_id_const() — + \c const version of this function. +*/ +extern bt_event_class * +bt_stream_class_borrow_event_class_by_id( + bt_stream_class *stream_class, uint64_t id); + +/*! +@brief + Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the + stream class \bt_p{stream_class} (\c const version). + +See bt_stream_class_borrow_event_class_by_id(). +*/ +extern const bt_event_class * +bt_stream_class_borrow_event_class_by_id_const( + const bt_stream_class *stream_class, uint64_t id); + +/*! @} */ + +/*! +@name Properties +@{ +*/ + +/*! +@brief + Returns the numeric ID of the stream class \bt_p{stream_class}. + +See the \ref api-tir-stream-cls-prop-id "numeric ID" property. + +@param[in] stream_class + Stream class of which to get the numeric ID. + +@returns + Numeric ID of \bt_p{stream_class}. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_create_with_id() — + Creates a stream class with a specific numeric ID and adds it to a + trace class. +*/ +extern uint64_t bt_stream_class_get_id( + const bt_stream_class *stream_class); + +/*! +@brief + Status codes for bt_stream_class_set_name(). +*/ typedef enum bt_stream_class_set_name_status { - BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_STREAM_CLASS_SET_NAME_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_stream_class_set_name_status; +/*! +@brief + Sets the name of the stream class \bt_p{stream_class} to + a copy of \bt_p{name}. + +See the \ref api-tir-stream-cls-prop-name "name" property. + +@param[in] stream_class + Stream class of which to set the name to \bt_p{name}. +@param[in] name + New name of \bt_p{stream_class} (copied). + +@retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK + Success. +@retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@bt_pre_not_null{name} + +@sa bt_stream_class_get_name() — + Returns the name of a stream class. +*/ extern bt_stream_class_set_name_status bt_stream_class_set_name( bt_stream_class *stream_class, const char *name); -extern void bt_stream_class_set_assigns_automatic_event_class_id( - bt_stream_class *stream_class, bt_bool value); +/*! +@brief + Returns the name of the stream class \bt_p{stream_class}. -extern void bt_stream_class_set_assigns_automatic_stream_id( - bt_stream_class *stream_class, bt_bool value); +See the \ref api-tir-stream-cls-prop-name "name" property. -extern void bt_stream_class_set_supports_discarded_events( - bt_stream_class *stream_class, - bt_bool supports_discarded_events, - bt_bool with_default_clock_snapshots); +If \bt_p{stream_class} has no name, this function returns \c NULL. -extern void bt_stream_class_set_supports_discarded_packets( +@param[in] stream_class + Stream class of which to get the name. + +@returns + @parblock + Name of \bt_p{stream_class}, or \c NULL if none. + + The returned pointer remains valid as long as \bt_p{stream_class} + is not modified. + @endparblock + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_name() — + Sets the name of a stream class. +*/ +extern const char *bt_stream_class_get_name( + const bt_stream_class *stream_class); + +/*! +@brief + Status codes for bt_stream_class_set_default_clock_class(). +*/ +typedef enum bt_stream_class_set_default_clock_class_status { + /*! + @brief + Success. + */ + BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK, +} bt_stream_class_set_default_clock_class_status; + +/*! +@brief + Sets the default \bt_clock_cls of the stream class + \bt_p{stream_class} to \bt_p{clock_class}. + +See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" +property. + +@param[in] stream_class + Stream class of which to set the default clock class to + \bt_p{clock_class}. +@param[in] clock_class + New default clock class of \bt_p{stream_class}. + +@retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK + Success. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@bt_pre_not_null{clock_class} + +@sa bt_stream_class_borrow_default_clock_class() — + Borrows the default clock class of a stream class. +@sa bt_stream_class_borrow_default_clock_class_const() — + Borrows the default clock class of a stream class (\c const version). +*/ +extern bt_stream_class_set_default_clock_class_status +bt_stream_class_set_default_clock_class( bt_stream_class *stream_class, - bt_bool supports_discarded_packets, - bt_bool with_default_clock_snapshots); + bt_clock_class *clock_class); + +/*! +@brief + Borrows the default \bt_clock_cls from the stream class + \bt_p{stream_class}. + +See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" +property. +If \bt_p{stream_class} has no default clock class, this function +returns \c NULL. + +@param[in] stream_class + Stream class from which to borrow the default clock class. + +@returns + \em Borrowed reference of the default clock class of + \bt_p{stream_class}, or \c NULL if none. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_default_clock_class() — + Sets the default clock class of a stream class. +@sa bt_stream_class_borrow_default_clock_class_const() — + \c const version of this function. +*/ +extern bt_clock_class *bt_stream_class_borrow_default_clock_class( + bt_stream_class *stream_class); + +/*! +@brief + Borrows the default \bt_clock_cls from the stream class + \bt_p{stream_class} (\c const version). + +See bt_stream_class_borrow_default_clock_class(). +*/ +extern const bt_clock_class * +bt_stream_class_borrow_default_clock_class_const( + const bt_stream_class *stream_class); + +/*! +@brief + Status codes for bt_stream_class_set_packet_context_field_class() + and bt_stream_class_set_event_common_context_field_class(). +*/ typedef enum bt_stream_class_set_field_class_status { - BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, + /*! + @brief + Success. + */ BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Out of memory. + */ + BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, } bt_stream_class_set_field_class_status; -extern void bt_stream_class_set_supports_packets( - bt_stream_class *stream_class, bt_bool supports_packets, - bt_bool with_beginning_default_clock_snapshot, - bt_bool with_end_default_clock_snapshot); +/*! +@brief + Sets the packet context \bt_fc of the stream class + \bt_p{stream_class} to \bt_p{field_class}. + +See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class" +property. + +\bt_p{stream_class} must support packets (see +bt_stream_class_set_supports_packets()). +@param[in] stream_class + Stream class of which to set the packet context field class to + \bt_p{field_class}. +@param[in] field_class + New packet context field class of \bt_p{stream_class}. + +@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK + Success. +@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@pre + bt_stream_class_supports_packets(stream_class) + returns #BT_TRUE. +@bt_pre_not_null{field_class} +@bt_pre_is_struct_fc{field_class} +@pre + \bt_p{field_class}, or any of its contained field classes, + is not already part of a stream class or of an \bt_ev_cls. +@pre + If any of the field classes recursively contained in + \bt_p{field_class} has a + \ref api-tir-fc-link "link to another field class", it must honor + the field class link rules. +@pre + If any of the field classes recursively contained in + \bt_p{field_class} has a + \ref api-tir-fc-link "link to another field class", it must honor + the field class link rules. + +@bt_post_success_frozen{field_class} + +@sa bt_stream_class_borrow_packet_context_field_class() — + Borrows the packet context field class of a stream class. +@sa bt_stream_class_borrow_packet_context_field_class_const() — + Borrows the packet context field class of a stream class + (\c const version). +*/ extern bt_stream_class_set_field_class_status bt_stream_class_set_packet_context_field_class( bt_stream_class *stream_class, bt_field_class *field_class); +/*! +@brief + Borrows the packet context \bt_fc from the stream class + \bt_p{stream_class}. + +See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class" +property. + +If \bt_p{stream_class} has no packet context field class, this function +returns \c NULL. + +@param[in] stream_class + Stream class from which to borrow the packet context field class. + +@returns + \em Borrowed reference of the packet context field class of + \bt_p{stream_class}, or \c NULL if none. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_packet_context_field_class() — + Sets the packet context field class of a stream class. +@sa bt_stream_class_borrow_packet_context_field_class_const() — + \c const version of this function. +*/ extern bt_field_class * bt_stream_class_borrow_packet_context_field_class( bt_stream_class *stream_class); +/*! +@brief + Borrows the packet context \bt_fc from the stream class + \bt_p{stream_class} (\c const version). + +See bt_stream_class_borrow_packet_context_field_class(). +*/ +extern const bt_field_class * +bt_stream_class_borrow_packet_context_field_class_const( + const bt_stream_class *stream_class); + +/*! +@brief + Sets the event common context \bt_fc of the stream class + \bt_p{stream_class} to \bt_p{field_class}. + +See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class" +property. + +@param[in] stream_class + Stream class of which to set the event common context field class to + \bt_p{field_class}. +@param[in] field_class + New event common context field class of \bt_p{stream_class}. + +@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK + Success. +@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR + Out of memory. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@bt_pre_not_null{field_class} +@bt_pre_is_struct_fc{field_class} +@pre + \bt_p{field_class}, or any of its contained field classes, + is not already part of a stream class or of an \bt_ev_cls. +@pre + If any of the field classes recursively contained in + \bt_p{field_class} has a + \ref api-tir-fc-link "link to another field class", it must honor + the field class link rules. + +@bt_post_success_frozen{field_class} + +@sa bt_stream_class_borrow_event_common_context_field_class() — + Borrows the event common context field class of a stream class. +@sa bt_stream_class_borrow_event_common_context_field_class_const() — + Borrows the event common context field class of a stream class + (\c const version). +*/ extern bt_stream_class_set_field_class_status bt_stream_class_set_event_common_context_field_class( bt_stream_class *stream_class, bt_field_class *field_class); +/*! +@brief + Borrows the event common context \bt_fc from the stream class + \bt_p{stream_class}. + +See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class" +property. + +If \bt_p{stream_class} has no event common context field class, this +function returns \c NULL. + +@param[in] stream_class + Stream class from which to borrow the event common context + field class. + +@returns + \em Borrowed reference of the event common context field class of + \bt_p{stream_class}, or \c NULL if none. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_event_common_context_field_class() — + Sets the event common context field class of a stream class. +@sa bt_stream_class_borrow_event_common_context_field_class_const() — + \c const version of this function. +*/ + extern bt_field_class * bt_stream_class_borrow_event_common_context_field_class( bt_stream_class *stream_class); -extern bt_event_class * -bt_stream_class_borrow_event_class_by_index( - bt_stream_class *stream_class, uint64_t index); +/*! +@brief + Borrows the event common context \bt_fc from the stream class + \bt_p{stream_class} (\c const version()). -extern bt_event_class * -bt_stream_class_borrow_event_class_by_id( - bt_stream_class *stream_class, uint64_t id); +See bt_stream_class_borrow_event_common_context_field_class(). +*/ +extern const bt_field_class * +bt_stream_class_borrow_event_common_context_field_class_const( + const bt_stream_class *stream_class); -extern bt_clock_class *bt_stream_class_borrow_default_clock_class( - bt_stream_class *stream_class); +/*! +@brief + Sets whether or not the stream class \bt_p{stream_class} + automatically assigns a numeric ID to an \bt_ev_cls you create and + add to it. -typedef enum bt_stream_class_set_default_clock_class_status { - BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_stream_class_set_default_clock_class_status; +See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?" +property. -extern bt_stream_class_set_default_clock_class_status -bt_stream_class_set_default_clock_class( +@param[in] stream_class + Stream class of which to set whether or not it assigns automatic + event class IDs. +@param[in] assigns_automatic_event_class_id + #BT_TRUE to make \bt_p{stream_class} assign automatic event class + IDs. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} + +@sa bt_stream_class_assigns_automatic_event_class_id() — + Returns whether or not a stream class automatically assigns + event class IDs. +*/ +extern void bt_stream_class_set_assigns_automatic_event_class_id( bt_stream_class *stream_class, - bt_clock_class *clock_class); + bt_bool assigns_automatic_event_class_id); + +/*! +@brief + Returns whether or not the stream class \bt_p{stream_class} + automatically assigns a numeric ID to an \bt_ev_cls you create + and add to it. + +See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?" +property. + +@param[in] stream_class + Stream class of which to get whether or not it assigns automatic + event class IDs. + +@returns + #BT_TRUE if \bt_p{stream_class} automatically + assigns event class IDs. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_assigns_automatic_event_class_id() — + Sets whether or not a stream class automatically assigns + event class IDs. +*/ +extern bt_bool bt_stream_class_assigns_automatic_event_class_id( + const bt_stream_class *stream_class); + +/*! +@brief + Sets whether or not the stream class \bt_p{stream_class} + automatically assigns a numeric ID to a \bt_stream you create from + it. + +See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?" +property. + +@param[in] stream_class + Stream class of which to set whether or not it assigns automatic + stream IDs. +@param[in] assigns_automatic_stream_id + #BT_TRUE to make \bt_p{stream_class} assign automatic stream + IDs. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} + +@sa bt_stream_class_assigns_automatic_stream_id() — + Returns whether or not a stream class automatically assigns + stream IDs. +*/ +extern void bt_stream_class_set_assigns_automatic_stream_id( + bt_stream_class *stream_class, bt_bool assigns_automatic_stream_id); + +/*! +@brief + Returns whether or not the stream class \bt_p{stream_class} + automatically assigns a numeric ID to a \bt_stream you create + from it. + +See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?" +property. + +@param[in] stream_class + Stream class of which to get whether or not it assigns automatic + stream IDs. + +@returns + #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_assigns_automatic_stream_id() — + Sets whether or not a stream class automatically assigns + stream IDs. +*/ +extern bt_bool bt_stream_class_assigns_automatic_stream_id( + const bt_stream_class *stream_class); + +/*! +@brief + Sets whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} have \bt_p_pkt and, if so, + if those packets have beginning and/or end default + \bt_p_cs. + +See the +\ref api-tir-stream-cls-prop-supports-pkt "supports packets?", +\ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?", +and +\ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?" +properties. + +@param[in] stream_class + Stream class of which to set whether or not its streams have + packets. +@param[in] supports_packets + #BT_TRUE to make the streams of \bt_p{stream_class} have packets. +@param[in] with_beginning_default_clock_snapshot + #BT_TRUE to make the packets of the streams of \bt_p{stream_class} + have a beginning default clock snapshot. +@param[in] with_end_default_clock_snapshot + #BT_TRUE to make the packets of the streams of \bt_p{stream_class} + have an end default clock snapshot. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@pre + If \bt_p{with_beginning_default_clock_snapshot} is + #BT_TRUE, + \bt_p{supports_packets} is also #BT_TRUE. +@pre + If \bt_p{with_beginning_default_clock_snapshot} is + #BT_TRUE, + \bt_p{supports_packets} is also #BT_TRUE. +@pre + If \bt_p{with_beginning_default_clock_snapshot} or + \bt_p{with_end_default_clock_snapshot} is #BT_TRUE, + \bt_p{stream_class} has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + +@sa bt_stream_class_supports_packets() — + Returns whether or not a stream class's streams have packets. +@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() — + Returns whether or not the packets of a stream class's streams + have a beginning default clock snapshot. +@sa bt_stream_class_packets_have_end_default_clock_snapshot() — + Returns whether or not the packets of a stream class's streams + have an end default clock snapshot. +*/ +extern void bt_stream_class_set_supports_packets( + bt_stream_class *stream_class, bt_bool supports_packets, + bt_bool with_beginning_default_clock_snapshot, + bt_bool with_end_default_clock_snapshot); + +/*! +@brief + Returns whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} have \bt_p_pkt. + +See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams have + packets. + +@returns + #BT_TRUE if the streams of \bt_p{stream_class} have packets. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_packets() — + Sets whether or not a stream class's streams have packets. +*/ +extern bt_bool bt_stream_class_supports_packets( + const bt_stream_class *stream_class); + +/*! +@brief + Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream) + of the stream class \bt_p{stream_class} have a beginning + default \bt_cs. + +See the +\ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams's packets + have a beginning default clock snapshot. + +@returns + #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a + beginning default clock snapshot. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_packets() — + Sets whether or not a stream class's streams have packets. +@sa bt_stream_class_packets_have_end_default_clock_snapshot() — + Returns whether or not the packets of a stream class's streams + have an end default clock snapshot. +*/ +extern bt_bool bt_stream_class_packets_have_beginning_default_clock_snapshot( + const bt_stream_class *stream_class); + +/*! +@brief + Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream) + of the stream class \bt_p{stream_class} have an end + default \bt_cs. + +See the +\ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams's packets + have an end default clock snapshot. + +@returns + #BT_TRUE if the packets of the streams of \bt_p{stream_class} have + an end default clock snapshot. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_packets() — + Sets whether or not a stream class's streams have packets. +@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() — + Returns whether or not the packets of a stream class's streams + have a beginning default clock snapshot. +*/ +extern bt_bool bt_stream_class_packets_have_end_default_clock_snapshot( + const bt_stream_class *stream_class); + +/*! +@brief + Sets whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} can have discarded events and, + if so, if the \bt_p_disc_ev_msg of those streams have + beginning and end default \bt_p_cs. + +See the +\ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?" +and +\ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?" +properties. + +@param[in] stream_class + Stream class of which to set whether or not its streams can have + discarded events. +@param[in] supports_discarded_events + #BT_TRUE to make the streams of \bt_p{stream_class} be able to + have discarded events. +@param[in] with_default_clock_snapshots + #BT_TRUE to make the discarded events messages the streams of + \bt_p{stream_class} have beginning and end default clock snapshots. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{supports_discarded_events} is also #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{stream_class} has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + +@sa bt_stream_class_supports_discarded_events() — + Returns whether or not a stream class's streams can have + discarded events. +@sa bt_stream_class_discarded_events_have_default_clock_snapshots() — + Returns whether or not the discarded events messages of a + stream class's streams have beginning and end default clock + snapshots. +*/ +extern void bt_stream_class_set_supports_discarded_events( + bt_stream_class *stream_class, + bt_bool supports_discarded_events, + bt_bool with_default_clock_snapshots); + +/*! +@brief + Returns whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} can have discarded events. + +See the +\ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams can have + discarded events. + +@returns + #BT_TRUE if the streams of \bt_p{stream_class} can have discarded + events. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_discarded_events() — + Sets whether or not a stream class's streams can have discarded + events. +*/ +extern bt_bool bt_stream_class_supports_discarded_events( + const bt_stream_class *stream_class); + +/*! +@brief + Returns whether or not the \bt_p_disc_ev_msg of the instances + (\bt_p_stream) of the stream class \bt_p{stream_class} have + beginning and end default \bt_p_cs. + +See the +\ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams's discarded + events messages have a beginning and end default clock snapshots. + +@returns + #BT_TRUE if the discarded events messages of the streams of + \bt_p{stream_class} have beginning and end default clock snapshots. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_discarded_events() — + Sets whether or not a stream class's streams can have discarded + events. +*/ +extern bt_bool bt_stream_class_discarded_events_have_default_clock_snapshots( + const bt_stream_class *stream_class); + +/*! +@brief + Sets whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} can have discarded packets and, + if so, if the \bt_p_disc_pkt_msg of those streams have + beginning and end default \bt_p_cs. + +See the +\ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?" +and +\ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?" +properties. + +\bt_p{stream_class} must support packets (see +bt_stream_class_set_supports_packets()). + +@param[in] stream_class + Stream class of which to set whether or not its streams can have + discarded packets. +@param[in] supports_discarded_packets + #BT_TRUE to make the streams of \bt_p{stream_class} be able to + have discarded packets. +@param[in] with_default_clock_snapshots + #BT_TRUE to make the discarded packets messages the streams of + \bt_p{stream_class} have beginning and end default clock snapshots. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@pre + bt_stream_class_supports_packets(stream_class) + returns #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{supports_discarded_packets} is also #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{stream_class} has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class". + +@sa bt_stream_class_supports_discarded_packets() — + Returns whether or not a stream class's streams can have + discarded packets. +@sa bt_stream_class_discarded_packets_have_default_clock_snapshots() — + Returns whether or not the discarded packets messages of a + stream class's streams have beginning and end default clock + snapshots. +*/ +extern void bt_stream_class_set_supports_discarded_packets( + bt_stream_class *stream_class, + bt_bool supports_discarded_packets, + bt_bool with_default_clock_snapshots); + +/*! +@brief + Returns whether or not the instances (\bt_p_stream) of the + stream class \bt_p{stream_class} can have discarded packets. + +See the +\ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams can have + discarded packets. + +@returns + #BT_TRUE if the streams of \bt_p{stream_class} can have discarded + packets. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_discarded_packets() — + Sets whether or not a stream class's streams can have discarded + packets. +*/ +extern bt_bool bt_stream_class_supports_discarded_packets( + const bt_stream_class *stream_class); + +/*! +@brief + Returns whether or not the \bt_p_disc_pkt_msg of the instances + (\bt_p_stream) of the stream class \bt_p{stream_class} have + beginning and end default \bt_p_cs. + +See the +\ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?" +property. + +@param[in] stream_class + Stream class of which to get whether or not its streams's discarded + packets messages have a beginning and end default clock snapshots. + +@returns + #BT_TRUE if the discarded packets messages of the streams of + \bt_p{stream_class} have beginning and end default clock snapshots. + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_supports_discarded_packets() — + Sets whether or not a stream class's streams can have discarded + packets. +*/ +extern bt_bool bt_stream_class_discarded_packets_have_default_clock_snapshots( + const bt_stream_class *stream_class); + +/*! +@brief + Sets the user attributes of the stream class \bt_p{stream_class} to + \bt_p{user_attributes}. + +See the \ref api-tir-stream-cls-prop-user-attrs "user attributes" +property. + +@note + When you create a default stream class with bt_stream_class_create() + or bt_stream_class_create_with_id(), the stream class's initial user + attributes is an empty \bt_map_val. Therefore you can borrow it with + bt_stream_class_borrow_user_attributes() and fill it directly + instead of setting a new one with this function. + +@param[in] stream_class + Stream class of which to set the user attributes to + \bt_p{user_attributes}. +@param[in] user_attributes + New user attributes of \bt_p{stream_class}. + +@bt_pre_not_null{stream_class} +@bt_pre_hot{stream_class} +@bt_pre_not_null{user_attributes} +@bt_pre_is_map_val{user_attributes} + +@sa bt_stream_class_borrow_user_attributes() — + Borrows the user attributes of a stream class. +*/ +extern void bt_stream_class_set_user_attributes( + bt_stream_class *stream_class, const bt_value *user_attributes); + +/*! +@brief + Borrows the user attributes of the stream class \bt_p{stream_class}. + +See the \ref api-tir-stream-cls-prop-user-attrs "user attributes" +property. + +@note + When you create a default stream class with bt_stream_class_create() + or bt_stream_class_create_with_id(), the stream class's initial user + attributes is an empty \bt_map_val. + +@param[in] stream_class + Stream class from which to borrow the user attributes. + +@returns + User attributes of \bt_p{stream_class} (a \bt_map_val). + +@bt_pre_not_null{stream_class} + +@sa bt_stream_class_set_user_attributes() — + Sets the user attributes of a stream class. +@sa bt_stream_class_borrow_user_attributes_const() — + \c const version of this function. +*/ +extern bt_value *bt_stream_class_borrow_user_attributes( + bt_stream_class *stream_class); + +/*! +@brief + Borrows the user attributes of the stream class \bt_p{stream_class} + (\c const version). + +See bt_stream_class_borrow_user_attributes(). +*/ +extern const bt_value *bt_stream_class_borrow_user_attributes_const( + const bt_stream_class *stream_class); + +/*! @} */ + +/*! +@name Reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the stream class \bt_p{stream_class}. + +@param[in] stream_class + @parblock + Stream class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_stream_class_put_ref() — + Decrements the reference count of a stream class. +*/ +extern void bt_stream_class_get_ref(const bt_stream_class *stream_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the stream class \bt_p{stream_class}. + +@param[in] stream_class + @parblock + Stream class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_stream_class_get_ref() — + Increments the reference count of a stream class. +*/ +extern void bt_stream_class_put_ref(const bt_stream_class *stream_class); + +/*! +@brief + Decrements the reference count of the stream class + \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL. + +@param _stream_class + @parblock + Stream class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_stream_class} +*/ +#define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class) \ + do { \ + bt_stream_class_put_ref(_stream_class); \ + (_stream_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the stream class \bt_p{_dst}, sets + \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. + +This macro effectively moves a stream class reference from the expression +\bt_p{_src} to the expression \bt_p{_dst}, putting the existing +\bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_STREAM_CLASS_MOVE_REF(_dst, _src) \ + do { \ + bt_stream_class_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! @} */ #ifdef __cplusplus }