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: + +
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 + |
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 + |
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
}