X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream.h;h=443e757e269e7bd6fefe6702c4242454f61a5c98;hb=50842bdc4c21f3de2b63e29cdac730af8b6dcca6;hp=b38d80d43a1777a5d268664029582cb48d967ce5;hpb=9f476966aa40bd0de2cd0654623ea03f8a3254eb;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/stream.h b/include/babeltrace/ctf-ir/stream.h index b38d80d4..443e757e 100644 --- a/include/babeltrace/ctf-ir/stream.h +++ b/include/babeltrace/ctf-ir/stream.h @@ -30,206 +30,192 @@ * http://www.efficios.com/ctf */ -#include +#include #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 +@endcode + +@note +See \ref ctfwriterstream which documents additional CTF IR stream +functions exclusive to the CTF writer mode. + +A CTF IR stream is an instance of a +\link ctfirstreamclass CTF IR stream class\endlink. + +You can obtain a CTF IR stream object in two different modes: + +- Normal mode: 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. +- CTF writer mode: 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 +reference +counts. 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 }