extern "C" {
#endif
+/*!
+@defgroup api-tir-stream-cls Stream class
+@ingroup api-tir
+
+@brief
+ Class of \bt_p_stream.
+
+A <strong><em>stream class</em></strong> 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:
+
+<dl>
+ <dt>Default clock</dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt>Discarded events</dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt>Discarded packets</dt>
+ <dd>
+ 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.
+ </dd>
+</dl>
+
+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:
+
+<dl>
+ <dt>
+ If bt_trace_class_assigns_automatic_stream_class_id() returns
+ #BT_TRUE (the default) for the trace class to use
+ </dt>
+ <dd>Use bt_stream_class_create().</dd>
+
+ <dt>
+ If bt_trace_class_assigns_automatic_stream_class_id() returns
+ #BT_FALSE for the trace class to use
+ </dt>
+ <dd>Use bt_stream_class_create_with_id().</dd>
+</dl>
+
+<h1>Properties</h1>
+
+A stream class has the following properties:
+
+<dl>
+ <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
+ <dd>
+ Name of the stream class.
+
+ Use bt_stream_class_set_name() and bt_stream_class_get_name().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-def-clock-cls
+ \bt_dt_opt Default clock class
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pc-fc
+ \bt_dt_opt Packet context field class
+ </dt>
+ <dd>
+ \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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-ecc-fc
+ \bt_dt_opt Event common context field class
+ </dt>
+ <dd>
+ \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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-auto-ec-id
+ Assigns automatic event class IDs?
+ </dt>
+ <dd>
+ 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:
+
+ <dl>
+ <dt>#BT_TRUE</dt>
+ <dd>
+ Use bt_event_class_create().
+ </dd>
+
+ <dt>#BT_FALSE</dt>
+ <dd>
+ Use bt_event_class_create_with_id().
+ </dd>
+ </dl>
+
+ Use bt_stream_class_set_assigns_automatic_event_class_id()
+ and bt_stream_class_assigns_automatic_event_class_id().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-auto-stream-id
+ Assigns automatic stream IDs?
+ </dt>
+ <dd>
+ 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:
+
+ <dl>
+ <dt>#BT_TRUE</dt>
+ <dd>
+ Use bt_stream_create().
+ </dd>
+
+ <dt>#BT_FALSE</dt>
+ <dd>
+ Use bt_stream_create_with_id().
+ </dd>
+ </dl>
+
+ Use bt_stream_class_set_assigns_automatic_stream_id()
+ and bt_stream_class_assigns_automatic_stream_id().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-pkt
+ Supports packets?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pkt-beg-cs
+ Packets have a beginning default clock snapshot?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-pkt-end-cs
+ Packets have an end default clock snapshot?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-disc-ev
+ Supports discarded events?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-disc-ev-cs
+ Discarded events have default clock snapshots?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-supports-disc-pkt
+ Supports discarded packets?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-disc-pkt-cs
+ Discarded packets have default clock snapshots?
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-tir-stream-cls-prop-user-attrs
+ \bt_dt_opt User attributes
+ </dt>
+ <dd>
+ 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().
+ </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@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:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
+ <td>Automatically assigned by \bt_p{trace_class}
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-name "Name"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@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
+ <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
+ 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:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
+ <td>\bt_p{id}
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-name "Name"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
+ <td>Yes
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
+ <td>No
+ <tr>
+ <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@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
+ <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
+ 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
+ <code>bt_stream_class_supports_packets(stream_class)</code>
+ 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
+ <strong>If \bt_p{with_beginning_default_clock_snapshot} is
+ #BT_TRUE</strong>,
+ \bt_p{supports_packets} is also #BT_TRUE.
+@pre
+ <strong>If \bt_p{with_beginning_default_clock_snapshot} is
+ #BT_TRUE</strong>,
+ \bt_p{supports_packets} is also #BT_TRUE.
+@pre
+ <strong>If \bt_p{with_beginning_default_clock_snapshot} or
+ \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
+ \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
+ <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+ \bt_p{supports_discarded_events} is also #BT_TRUE.
+@pre
+ <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+ \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
+ <code>bt_stream_class_supports_packets(stream_class)</code>
+ returns #BT_TRUE.
+@pre
+ <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+ \bt_p{supports_discarded_packets} is also #BT_TRUE.
+@pre
+ <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+ \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
}
projects / babeltrace.git / blobdiff