extern "C" {
#endif
-struct bt_ctf_event_class;
+/**
+@defgroup ctfirstreamclass CTF IR stream class
+@ingroup ctfir
+@brief CTF IR stream class.
+
+A CTF IR <strong><em>stream class</em></strong> is a template that you
+can use to create concrete \link ctfirstream CTF IR streams\endlink.
+
+A stream class has the following properties, both of which \em must
+be unique amongst all the stream classes contained in the same
+\link ctfirtraceclass CTF IR trace class\endlink:
+
+- A \b name.
+- A numeric \b ID.
+
+In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
+contains zero or more stream classes,
+and a stream class contains zero or more
+\link ctfireventclass event classes\endlink.
+You can add an event class
+to a stream class with bt_ctf_stream_class_add_event_class().
+You can add a stream class to a trace class with
+bt_ctf_trace_add_stream_class().
+
+A stream class owns three \link ctfirfieldtypes field types\endlink:
+
+- An optional <strong>stream packet context</strong> field type, which
+ represents the \c stream.packet.context CTF scope.
+- An optional <strong>stream event header</strong> field type, which
+ represents the \c stream.event.header CTF scope.
+- An optional <strong>stream event context</strong> field type, which
+ represents the \c stream.event.context CTF scope.
+
+Those three field types \em must be structure field types as of
+Babeltrace \btversion.
+
+As per the CTF specification, the event header field type \em must
+contain a field named \c id if the stream class contains more than one
+event class.
+
+As a reminder, here's the structure of a CTF packet:
+
+@imgpacketstructure
+
+Before you can create a stream from a stream class with
+bt_ctf_stream_create(), you \em must add the prepared stream class to a
+trace class by calling bt_ctf_trace_add_stream_class().
+
+As with any Babeltrace object, CTF IR stream class objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+The following functions \em freeze their stream class parameter on
+success:
+
+- bt_ctf_trace_add_stream_class()
+- bt_ctf_event_create()
+- bt_ctf_writer_create_stream()
+ (\link ctfirwriter CTF writer\endlink mode only)
+
+You cannot modify a frozen stream class: it is considered immutable,
+except for:
+
+- Adding an event class to it with
+ bt_ctf_stream_class_add_event_class().
+- \link refs Reference counting\endlink.
+
+@sa ctfirstream
+@sa ctfireventclass
+@sa ctfirtraceclass
+
+@file
+@brief CTF IR stream class type and functions.
+@sa ctfirstreamclass
+
+@addtogroup ctfirstreamclass
+@{
+*/
+
+/**
+@struct bt_ctf_stream_class
+@brief A CTF IR stream class.
+@sa ctfirstreamclass
+*/
struct bt_ctf_stream_class;
+struct bt_ctf_event_class;
struct bt_ctf_clock;
-/*
- * bt_ctf_stream_class_create: create a stream class.
- *
- * Allocate a new stream class of the given name. The creation of an event class
- * sets its reference count to 1.
- *
- * A stream class' packet context is a structure initialized with the following
- * fields:
- * - uint64_t timestamp_begin
- * - uint64_t timestamp_end
- * - uint64_t content_size
- * - uint64_t packet_size
- * - uint64_t events_discarded
- *
- * A stream class's event header is a structure initialized the following
- * fields:
- * - uint32_t id
- * - uint64_t timestamp
- *
- * @param name Stream name, NULL to create an unnamed stream class.
- *
- * Returns an allocated stream class on success, NULL on error.
- */
+/**
+@name Creation and parent access functions
+@{
+*/
+
+/**
+@brief Creates a default CTF IR stream class named \p name, or a
+ default unnamed stream class if \p name is \c NULL.
+
+On success, the packet context field type of the created stream class
+has the following fields:
+
+- <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
+- <code>timestamp_end</code>: a 64-bit unsigned integer field type.
+- <code>content_size</code>: a 64-bit unsigned integer field type.
+- <code>packet_size</code>: a 64-bit unsigned integer field type.
+- <code>events_discarded</code>: a 64-bit unsigned integer field type.
+
+On success, the event header field type of the created stream class
+has the following fields:
+
+- <code>code</code>: a 32-bit unsigned integer field type.
+- <code>timestamp</code>: a 64-bit unsigned integer field type.
+
+You can modify those default field types after the stream class is
+created with bt_ctf_stream_class_set_packet_context_type() and
+bt_ctf_stream_class_set_event_header_type().
+
+@param[in] name Name of the stream class to create (can be \c NULL to
+ create an unnamed stream class).
+@returns Created stream class, or \c NULL on error.
+
+@postsuccessrefcountret1
+*/
extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name);
-/*
- * bt_ctf_stream_class_get_trace: Get a stream class' associated trace.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream class' associated trace, NULL on error.
- */
+/**
+@brief Returns the parent CTF IR trace class of the CTF IR stream
+ class \p stream_class.
+
+It is possible that the stream class was not added to a trace class
+yet, in which case this function returns \c NULL. You can add a
+stream class to a trace class with
+bt_ctf_trace_add_stream_class().
+
+@param[in] stream_class Stream class of which to get the parent
+ trace class.
+@returns Parent trace class of \p stream_class,
+ or \c NULL if \p stream_class was not
+ added to a trace class yet or on error.
+
+@prenotnull{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_trace_add_stream_class(): Add a stream class to
+ a trace class.
+*/
extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_get_name: Get a stream class' name.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream class' name, NULL on error.
- */
+/** @} */
+
+/**
+@name Properties functions
+@{
+*/
+
+/**
+@brief Returns the name of the CTF IR stream class \p stream_class.
+
+On success, \p stream_class remains the sole owner of the returned
+string.
+
+@param[in] stream_class Stream class of which to get the name.
+@returns Name of stream class \p stream_class, or
+ \c NULL if \p stream_class is unnamed or
+ on error.
+
+@prenotnull{stream_class}
+@postrefcountsame{stream_class}
+
+@sa bt_ctf_stream_class_set_name(): Sets the name of a given
+ stream class.
+*/
extern const char *bt_ctf_stream_class_get_name(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_set_name: Set a stream class' name.
- *
- * @param stream_class Stream class.
- *
- * Returns 0 on success, a negative value on error.
- */
+/**
+@brief Sets the name of the CTF IR stream class
+ \p stream_class to \p name.
+
+\p name must be unique amongst the names of all the stream classes
+of the trace class to which you eventually add \p stream_class.
+
+@param[in] stream_class Stream class of which to set the name.
+@param[in] name Name of the stream class (copied on success).
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{name}
+@prehot{stream_class}
+@postrefcountsame{stream_class}
+
+@sa bt_ctf_stream_class_get_name(): Returns the name of a given
+ stream class.
+*/
extern int bt_ctf_stream_class_set_name(
struct bt_ctf_stream_class *stream_class, const char *name);
-/*
- * bt_ctf_stream_class_get_clock: get the clock associated with a stream class.
- *
- * @param stream_class Stream class.
- *
- * Returns a clock instance, NULL on error.
- */
-extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
- struct bt_ctf_stream_class *stream_class);
+/**
+@brief Returns the numeric ID of the CTF IR stream class \p stream_class.
-/*
- * bt_ctf_stream_class_get_id: Get a stream class' id.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream class' id, a negative value on error.
- */
+@param[in] stream_class Stream class of which to get the numeric ID.
+@returns ID of stream class \p stream_class, or a
+ negative value on error.
+
+@prenotnull{stream_class}
+@postrefcountsame{stream_class}
+
+@sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
+ stream class.
+*/
extern int64_t bt_ctf_stream_class_get_id(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_set_id: Set a stream class' id.
- *
- * Set a stream class' id. Must be unique trace-wise.
- * Note that stream classes are assigned a unique id when a stream instance
- * is created for the first time from a trace or writer.
- *
- * @param stream_class Stream class.
- * @param id Stream class id.
- *
- * Returns 0 on success, a negative value on error.
- */
+/**
+@brief Sets the numeric ID of the CTF IR stream class
+ \p stream_class to \p id.
+
+\p id must be unique amongst the IDs of all the stream classes
+of the trace class to which you eventually add \p stream_class.
+
+@param[in] stream_class Stream class of which to set the numeric ID.
+@param[in] id ID of the stream class.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prehot{stream_class}
+@postrefcountsame{stream_class}
+
+@sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
+ stream class.
+*/
extern int bt_ctf_stream_class_set_id(
struct bt_ctf_stream_class *stream_class, uint32_t id);
-/*
- * bt_ctf_stream_class_add_event_class: add an event class to a stream class.
- *
- * Add an event class to a stream class. New events can be added even after a
- * stream has beem instanciated and events have been appended. However, a stream
- * will not accept events of a class that has not been registered beforehand.
- * The stream class will share the ownership of "event_class" by incrementing
- * its reference count.
- *
- * Note that an event class may only be added to one stream class. It
- * also becomes immutable.
- *
- * @param stream_class Stream class.
- * @param event_class Event class to add to the provided stream class.
- *
- * Returns 0 on success, a negative value on error.
- */
-extern int bt_ctf_stream_class_add_event_class(
- struct bt_ctf_stream_class *stream_class,
- struct bt_ctf_event_class *event_class);
+/** @} */
-/*
- * bt_ctf_stream_class_get_event_class_count: Get a stream class' event class
- * count.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream class' event count, a negative value on error.
- */
-extern int bt_ctf_stream_class_get_event_class_count(
- struct bt_ctf_stream_class *stream_class);
+/**
+@name Contained field types functions
+@{
+*/
-/*
- * bt_ctf_stream_class_get_event_class: Get stream class event class by index.
- *
- * @param stream_class Stream class.
- * @param index Index of field.
- *
- * Returns event class, NULL on error.
- */
-extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
- struct bt_ctf_stream_class *stream_class, int index);
+/**
+@brief Returns the packet context field type of the CTF IR stream class
+ \p stream_class.
-/*
- * bt_ctf_stream_class_get_event_class_by_name: Get stream class event class by
- * name.
- *
- * @param stream_class Stream class.
- * @param name Event name.
- *
- * Returns event class, NULL on error.
- */
-extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
- struct bt_ctf_stream_class *stream_class, const char *name);
+@param[in] stream_class Stream class of which to get the packet
+ context field type.
+@returns Packet context field type of \p stream_class,
+ or \c NULL on error.
-/*
- * bt_ctf_stream_class_get_event_class_by_name: Get stream class event class by
- * ID.
- *
- * @param stream_class Stream class.
- * @param id Event class ID.
- *
- * Returns event class, NULL on error.
- */
-extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
- struct bt_ctf_stream_class *stream_class, uint32_t id);
+@prenotnull{stream_class}
+@postsuccessrefcountretinc
-/*
- * bt_ctf_stream_class_get_packet_context_type: get the stream class' packet
- * context type.
- *
- * @param stream_class Stream class.
- *
- * Returns the packet context's type (a structure), NULL on error.
- */
+@sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
+ context field type of a given stream class.
+*/
extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_set_packet_context_type: set the stream class' packet
- * context type.
- *
- * @param stream_class Stream class.
- * @param packet_context_type Packet context type (must be a structure).
- *
- * Returns 0 on success, a negative value on error.
- */
+/**
+@brief Sets the packet context field type of the CTF IR stream class
+ \p stream_class to \p packet_context_type.
+
+As of Babeltrace \btversion, \p packet_context_type \em must be a
+CTF IR structure field type object.
+
+@param[in] stream_class Stream class of which to set the packet
+ context field type.
+@param[in] packet_context_type Packet context field type.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{packet_context_type}
+@prehot{stream_class}
+@preisstructft{packet_context_type}
+@postrefcountsame{stream_class}
+@postsuccessrefcountinc{packet_context_type}
+
+@sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
+ context field type of a given stream class.
+*/
extern int bt_ctf_stream_class_set_packet_context_type(
struct bt_ctf_stream_class *stream_class,
struct bt_ctf_field_type *packet_context_type);
-/*
- * bt_ctf_stream_class_get_event_header_type: get the stream class'
- * event header type.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream event header's type (a structure), NULL on error.
- */
+/**
+@brief Returns the event header field type of the CTF IR stream class
+ \p stream_class.
+
+@param[in] stream_class Stream class of which to get the event header
+ field type.
+@returns Event header field type of \p stream_class,
+ or \c NULL on error.
+
+@prenotnull{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_stream_class_set_event_header_type(): Sets the event
+ header field type of a given stream class.
+*/
extern struct bt_ctf_field_type *
bt_ctf_stream_class_get_event_header_type(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_set_event_header_type: set the stream class'
- * event header type.
- *
- * @param stream_class Stream class.
- * @param event_header_type Event header type (must be a structure).
- *
- * Returns 0 on success, a negative value on error.
- */
+/**
+@brief Sets the event header field type of the CTF IR stream class
+ \p stream_class to \p event_header_type.
+
+As of Babeltrace \btversion, \p event_header_type \em must be a
+CTF IR structure field type object.
+
+@param[in] stream_class Stream class of which to set the event
+ header field type.
+@param[in] event_header_type Event header field type.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{event_header_type}
+@prehot{stream_class}
+@preisstructft{event_header_type}
+@postrefcountsame{stream_class}
+@postsuccessrefcountinc{event_header_type}
+
+@sa bt_ctf_stream_class_get_event_header_type(): Returns the event
+ header field type of a given stream class.
+*/
extern int bt_ctf_stream_class_set_event_header_type(
struct bt_ctf_stream_class *stream_class,
struct bt_ctf_field_type *event_header_type);
-/*
- * bt_ctf_stream_class_get_event_context_type: get the stream class'
- * event context type.
- *
- * @param stream_class Stream class.
- *
- * Returns the stream event context's type (a structure), NULL on error.
- */
+/**
+@brief Returns the per-stream class event context field type of the
+ CTF IR stream class \p stream_class.
+
+@param[in] stream_class Stream class of which to get the per-stream
+ class event context field type.
+@returns Per-stream class event context field type of
+ \p stream_class, or \c NULL on error.
+
+@prenotnull{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
+ class event context field type of a given stream class.
+*/
extern struct bt_ctf_field_type *
bt_ctf_stream_class_get_event_context_type(
struct bt_ctf_stream_class *stream_class);
-/*
- * bt_ctf_stream_class_set_event_context_type: set the stream class'
- * event context type.
- *
- * @param stream_class Stream class.
- * @param event_context_type Event context type (must be a structure).
- *
- * Returns 0 on success, a negative value on error.
- */
+/**
+@brief Sets the per-stream class event context field type of the CTF
+ IR stream class \p stream_class to \p event_context_type.
+
+As of Babeltrace \btversion, \p event_context_type \em must be a
+CTF IR structure field type object.
+
+@param[in] stream_class Stream class of which to set the
+ per-stream class event context
+ field type.
+@param[in] event_context_type Per-stream class event context context
+ field type.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{event_context_type}
+@prehot{stream_class}
+@preisstructft{event_context_type}
+@postrefcountsame{stream_class}
+@postsuccessrefcountinc{event_context_type}
+
+@sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
+ class event context field type of a given stream class.
+*/
extern int bt_ctf_stream_class_set_event_context_type(
struct bt_ctf_stream_class *stream_class,
struct bt_ctf_field_type *event_context_type);
-/*
- * bt_ctf_stream_class_visit: visit a stream class' event classes.
- *
- * Call visitor on each of a stream class' event classes.
- *
- * @param stream_class Stream class instance.
- * @param visitor visitor function to invoke for each stream class.
- * @param data user data passed to the visitor.
- *
- * Returns 0 on success, a negative value on error.
- */
+/** @} */
+
+/**
+@name Event class children functions
+@{
+*/
+
+/**
+@brief Returns the number of event classes contained in the
+ CTF IR stream class \p stream_class.
+
+@param[in] stream_class Stream class of which to get the number
+ of children event classes.
+@returns Number of children event classes
+ contained in \p stream_class, or
+ a negative value on error.
+
+@prenotnull{stream_class}
+@postrefcountsame{stream_class}
+*/
+extern int bt_ctf_stream_class_get_event_class_count(
+ struct bt_ctf_stream_class *stream_class);
+
+/**
+@brief Returns the event class at index \p index in the CTF IR stream
+ class \p stream_class.
+
+@param[in] stream_class Stream class of which to get the event class.
+@param[in] index Index of the event class to find.
+@returns Event class at index \p index, or \c NULL
+ on error.
+
+@prenotnull{stream_class}
+@pre \p index is lesser than the number of event classes contained in the
+ stream class \p stream_class (see
+ bt_ctf_stream_class_get_event_class_count()).
+@postrefcountsame{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
+ by ID.
+@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
+ by name.
+*/
+extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
+ struct bt_ctf_stream_class *stream_class, int index);
+
+/**
+@brief Returns the event class named \c name found in the CTF IR stream
+ class \p stream_class.
+
+@param[in] stream_class Stream class of which to get the event class.
+@param[in] name Name of the event class to find.
+@returns Event class named \p name, or \c NULL
+ on error.
+
+@prenotnull{stream_class}
+@prenotnull{name}
+@postrefcountsame{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
+ by ID.
+*/
+extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
+ struct bt_ctf_stream_class *stream_class, const char *name);
+
+/**
+@brief Returns the event class with ID \c id found in the CTF IR stream
+ class \p stream_class.
+
+@param[in] stream_class Stream class of which to get the event class.
+@param[in] id ID of the event class to find.
+@returns Event class with ID \p id, or \c NULL
+ on error.
+
+@prenotnull{stream_class}
+@postrefcountsame{stream_class}
+@postsuccessrefcountretinc
+
+@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
+ by name.
+*/
+extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
+ struct bt_ctf_stream_class *stream_class, uint32_t id);
+
+/**
+@brief Adds the CTF IR event class \p event_class to the
+ CTF IR stream class \p stream_class.
+
+On success, \p event_class becomes the child of \p stream_class.
+
+You can only add a given event class to one stream class.
+
+You can call this function even if \p stream_class is frozen. Adding
+event classes is the only operation that is permitted
+on a frozen stream class.
+
+@param[in] stream_class Stream class to which to add \p event_class.
+@param[in] event_class Event class to add to \p stream_class.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{event_class}
+@prehot{event_class}
+@postrefcountsame{stream_class}
+@postsuccessrefcountinc{event_class}
+*/
+extern int bt_ctf_stream_class_add_event_class(
+ struct bt_ctf_stream_class *stream_class,
+ struct bt_ctf_event_class *event_class);
+
+/** @} */
+
+/**
+@name Misc. function
+@{
+*/
+
+/**
+@brief Accepts the visitor \p visitor to visit the hierarchy of the
+ CTF IR stream class \p stream_class.
+
+This function traverses the hierarchy of \p stream_class in pre-order
+and calls \p visitor on each element.
+
+The stream class itself is visited first, and then all its children
+event classes.
+
+@param[in] stream_class Stream class to visit.
+@param[in] visitor Visiting function.
+@param[in] data User data.
+@returns 0 on success, or a negative value on error.
+
+@prenotnull{stream_class}
+@prenotnull{visitor}
+*/
extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class,
bt_ctf_ir_visitor visitor, void *data);
+/** @} */
+
+/** @} */
+
+// TODO: document for writer
+extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
+ struct bt_ctf_stream_class *stream_class);
+
#ifdef __cplusplus
}
#endif
projects / babeltrace.git / commitdiff
