* http://www.efficios.com/ctf
*/
-#include <babeltrace/ctf-ir/stream-class.h>
+#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
-struct bt_ctf_event;
-struct bt_ctf_stream;
+struct bt_stream_class;
+
+/**
+@defgroup ctfirstream CTF IR stream
+@ingroup ctfir
+@brief CTF IR stream.
+
+@code
+#include <babeltrace/ctf-ir/stream.h>
+@endcode
+
+@note
+See \ref ctfwriterstream which documents additional CTF IR stream
+functions exclusive to the CTF writer mode.
+
+A CTF IR <strong><em>stream</em></strong> is an instance of a
+\link ctfirstreamclass CTF IR stream class\endlink.
+
+You can obtain a CTF IR stream object in two different modes:
+
+- <strong>Normal mode</strong>: use bt_stream_create() or
+ bt_stream_create_with_id() with a stream class having a
+ \link ctfirtraceclass CTF IR trace class\endlink parent
+ \em not created by a \link ctfwriter CTF writer\endlink object to
+ create a default stream.
+- <strong>CTF writer mode</strong>: use bt_stream_create() with
+ a stream class having a trace class parent created by a CTF writer
+ object, or use bt_writer_create_stream().
+
+A CTF IR stream object represents a CTF stream, that is, a sequence of
+packets containing events:
+
+@imgtracestructure
+
+A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
+IR packet\endlink objects: it only acts as a common parent to identify
+the original CTF stream of packet objects.
+
+As with any Babeltrace object, CTF IR stream 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.
+
+@sa ctfirstreamclass
+@sa ctfirpacket
+@sa ctfwriterstream
+
+@file
+@brief CTF IR stream type and functions.
+@sa ctfirstream
+
+@addtogroup ctfirstream
+@{
+*/
+
+/**
+@struct bt_stream
+@brief A CTF IR stream.
+@sa ctfirstream
+@sa ctfwriterstream
+*/
+struct bt_stream;
+struct bt_event;
+
+/**
+@brief Creates a default CTF IR stream named \p name from the CTF IR
+ stream class \p stream_class.
+
+\p stream_class \em must have a parent
+\link ctfirtraceclass CTF IR trace class\endlink.
+
+If the parent \link ctfirtraceclass trace class\endlink of
+\p stream_class was created by a \link ctfwriter CTF writer\endlink
+object, then the stream object is created in CTF writer mode, and
+you can use the functions of \ref ctfwriterstream on it.
+Otherwise it is created in normal mode: you should only use the
+functions documented in this module on it.
+
+\p name can be \c NULL to create an unnamed stream object.
+
+@param[in] stream_class CTF IR stream class to use to create the
+ CTF IR stream.
+@param[in] name Name of the stream object to create (copied on
+ success) or \c NULL to create an unnamed stream.
+@returns Created stream object, or \c NULL on error.
+
+@prenotnull{stream_class}
+@pre \p stream_class has a parent trace class.
+@postsuccessrefcountret1
+
+@sa bt_stream_create_with_id(): Create a CTF IR stream with a
+ specific ID.
+*/
+extern struct bt_stream *bt_stream_create(
+ struct bt_stream_class *stream_class,
+ const char *name);
+
+/**
+@brief Creates a default CTF IR stream named \p name with ID \p id
+ from the CTF IR stream class \p stream_class.
+
+\p stream_class \em must have a parent
+\link ctfirtraceclass CTF IR trace class\endlink.
+
+You \em must have created the trace class of \p stream class directly
+with bt_trace_create(), not through bt_writer_create() (use
+bt_stream_create() for this).
+
+\p id \em must be unique amongst the IDs of all the streams created
+from \p stream_class with bt_stream_create_with_id().
+
+\p name can be \c NULL to create an unnamed stream object.
+
+@param[in] stream_class CTF IR stream class to use to create the
+ CTF IR stream.
+@param[in] name Name of the stream object to create (copied on
+ success) or \c NULL to create an unnamed stream.
+@param[in] id ID of the stream object to create.
+@returns Created stream object, or \c NULL on error.
+
+@prenotnull{stream_class}
+@pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
+@pre \p stream_class has a parent trace class.
+@postsuccessrefcountret1
+
+@sa bt_stream_create(): Create a CTF IR stream without an ID.
+*/
+extern struct bt_stream *bt_stream_create_with_id(
+ struct bt_stream_class *stream_class,
+ const char *name, uint64_t id);
+
+/**
+@brief Returns the name of the CTF IR stream \p stream.
+
+On success, \p stream remains the sole owner of the returned string.
+
+@param[in] stream Stream object of which to get the name.
+@returns Name of stream \p stream, or \c NULL if
+ \p stream is unnamed or on error.
+
+@prenotnull{stream}
+@postrefcountsame{stream}
+*/
+extern const char *bt_stream_get_name(struct bt_stream *stream);
+
+/**
+@brief Returns the numeric ID of the CTF IR stream \p stream.
+
+@param[in] stream Stream of which to get the numeric ID.
+@returns ID of stream \p stream, or a negative value
+ on error.
+
+@prenotnull{stream}
+@postrefcountsame{stream}
+*/
+extern int64_t bt_stream_get_id(struct bt_stream *stream);
+
+/**
+@brief Returns the parent CTF IR stream class of the CTF IR
+ stream \p stream.
+
+This function returns a reference to the stream class which was used
+to create the stream object in the first place with
+bt_stream_create().
+
+@param[in] stream Stream of which to get the parent stream class.
+@returns Parent stream class of \p stream,
+ or \c NULL on error.
+
+@prenotnull{stream}
+@postrefcountsame{stream}
+@postsuccessrefcountretinc
+*/
+extern struct bt_stream_class *bt_stream_get_class(
+ struct bt_stream *stream);
+
+/** @} */
-/*
- * bt_ctf_stream_get_stream_class: get a stream's class.
- *
- * @param stream Stream instance.
- *
- * Returns the stream's class, NULL on error.
- */
-extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
- struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_get_discarded_events_count: get the number of discarded
- * events associated with this stream.
- *
- * Note that discarded events are not stored if the stream's packet
- * context has no "events_discarded" field. An error will be returned
- * in that case.
- *
- * @param stream Stream instance.
- *
- * Returns the number of discarded events, a negative value on error.
- */
-extern int bt_ctf_stream_get_discarded_events_count(
- struct bt_ctf_stream *stream, uint64_t *count);
-
-/*
- * bt_ctf_stream_append_discarded_events: increment discarded events count.
- *
- * Increase the current packet's discarded event count. Has no effect if the
- * stream class' packet context has no "events_discarded" field.
- *
- * @param stream Stream instance.
- * @param event_count Number of discarded events to add to the stream's current
- * packet.
- */
-extern void bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream,
- uint64_t event_count);
-
-/*
- * bt_ctf_stream_append_event: append an event to the stream.
- *
- * Append "event" to the stream's current packet. The stream's associated clock
- * will be sampled during this call. The event shall not be modified after
- * being appended to a stream. The stream will share the event's ownership by
- * incrementing its reference count. The current packet is not flushed to disk
- * until the next call to bt_ctf_stream_flush.
- *
- * The stream event context will be sampled for every appended event if
- * a stream event context was defined.
- *
- * @param stream Stream instance.
- * @param event Event instance to append to the stream's current packet.
- *
- * Returns 0 on success, a negative value on error.
- */
-extern int bt_ctf_stream_append_event(struct bt_ctf_stream *stream,
- struct bt_ctf_event *event);
-
-/*
- * bt_ctf_stream_get_packet_header: get a stream's packet header.
- *
- * @param stream Stream instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern struct bt_ctf_field *bt_ctf_stream_get_packet_header(
- struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_set_packet_header: set a stream's packet header.
- *
- * The packet header's type must match the trace's packet header
- * type.
- *
- * @param stream Stream instance.
- * @param packet_header Packet header instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern int bt_ctf_stream_set_packet_header(
- struct bt_ctf_stream *stream,
- struct bt_ctf_field *packet_header);
-
-/*
- * bt_ctf_stream_get_packet_context: get a stream's packet context.
- *
- * @param stream Stream instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern struct bt_ctf_field *bt_ctf_stream_get_packet_context(
- struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_set_packet_context: set a stream's packet context.
- *
- * The packet context's type must match the stream class' packet
- * context type.
- *
- * @param stream Stream instance.
- * @param packet_context Packet context field instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern int bt_ctf_stream_set_packet_context(
- struct bt_ctf_stream *stream,
- struct bt_ctf_field *packet_context);
-
-/*
- * bt_ctf_stream_get_event_header: get a stream's event header.
- *
- * @param stream Stream instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern struct bt_ctf_field *bt_ctf_stream_get_event_header(
- struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_set_event_header: set a stream's event header.
- *
- * The event header's type must match the stream class' event
- * header type.
- *
- * @param stream Stream instance.
- * @param event_header Event header field instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern int bt_ctf_stream_set_event_context(
- struct bt_ctf_stream *stream,
- struct bt_ctf_field *event_context);
-
-/*
- * bt_ctf_stream_get_event_context: get a stream's event context.
- *
- * @param stream Stream instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern struct bt_ctf_field *bt_ctf_stream_get_event_context(
- struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_set_event_context: set a stream's event context.
- *
- * The event context's type must match the stream class' event
- * context type.
- *
- * @param stream Stream instance.
- * @param event_context Event context field instance.
- *
- * Returns a field instance on success, NULL on error.
- */
-extern int bt_ctf_stream_set_event_context(
- struct bt_ctf_stream *stream,
- struct bt_ctf_field *event_context);
-
-/*
- * bt_ctf_stream_flush: flush a stream.
- *
- * The stream's current packet's events will be flushed, thus closing the
- * current packet. Events subsequently appended to the stream will be
- * added to a new packet.
- *
- * Flushing will also set the packet context's default attributes if
- * they remained unset while populating the current packet. These default
- * attributes, along with their expected types, are detailed in stream-class.h.
- *
- * @param stream Stream instance.
- *
- * Returns 0 on success, a negative value on error.
- */
-extern int bt_ctf_stream_flush(struct bt_ctf_stream *stream);
-
-/*
- * bt_ctf_stream_get and bt_ctf_stream_put: increment and decrement the
- * stream's reference count.
- *
- * These functions ensure that the stream won't be destroyed while it
- * is in use. The same number of get and put (plus one extra put to
- * release the initial reference done at creation) have to be done to
- * destroy a stream.
- *
- * When the stream's reference count is decremented to 0 by a
- * bt_ctf_stream_put, the stream is freed.
- *
- * @param stream Stream instance.
- */
-extern void bt_ctf_stream_get(struct bt_ctf_stream *stream);
-extern void bt_ctf_stream_put(struct bt_ctf_stream *stream);
+/* Pre-2.0 CTF writer compatibility */
+#define bt_ctf_stream bt_stream
#ifdef __cplusplus
}
projects / babeltrace.git / blobdiff