X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Fstream.h;h=8de7e24378ec3e158db027419926c41382981f2f;hb=54f61f03e8dc0f9271b1c5e992bb95d69b2a4b6f;hp=e9f549b848caa3cdff3a48273c68dff255886296;hpb=a847c172f75ef6fe905c889866aedfbf75230769;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/stream.h b/include/babeltrace/ctf-ir/stream.h index e9f549b8..8de7e243 100644 --- a/include/babeltrace/ctf-ir/stream.h +++ b/include/babeltrace/ctf-ir/stream.h @@ -31,180 +31,126 @@ */ #include +#include #ifdef __cplusplus extern "C" { #endif -struct bt_ctf_event; -struct bt_ctf_stream; +/** +@defgroup ctfirstream CTF IR stream +@ingroup ctfir +@brief CTF IR 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); +@note +See \ref ctfirwriterstream which documents additional CTF IR stream +functions exclusive to the CTF IR writer mode. -/* - * 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); +A CTF IR stream is an instance of a +\link ctfirstreamclass CTF IR stream class\endlink. -/* - * 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); +You can obtain a CTF IR stream object in two different modes: -/* - * 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); +- Normal mode: use bt_ctf_stream_create() with a stream + class having a \link ctfirtraceclass CTF IR trace class\endlink parent + \em not created by a \link ctfirwriter CTF IR writer\endlink object to + create a default stream. +- CTF IR writer mode: use bt_ctf_stream_create() with + a stream class having a trace class parent created by a CTF IR writer + object, or use bt_ctf_writer_create_stream(). -/* - * 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); +A CTF IR stream object represents a CTF stream, that is, a sequence of +packets containing events: -/* - * 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); +@imgtracestructure -/* - * 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); +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. -/* - * 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_header( - struct bt_ctf_stream *stream, - struct bt_ctf_field *event_header); +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. -/* - * 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); +@sa ctfirstreamclass +@sa ctfirpacket +@sa ctfirwriterstream -/* - * 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); +@file +@brief CTF IR stream type and functions. +@sa ctfirstream -/* - * 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); +@addtogroup ctfirstream +@{ +*/ -/* - * 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); +struct bt_ctf_stream; +struct bt_ctf_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 ctfirwriter CTF IR writer\endlink +object, then the stream object is created in CTF IR writer mode, and +you can use the functions of \ref ctfirwriterstream 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 +*/ +extern struct bt_ctf_stream *bt_ctf_stream_create( + struct bt_ctf_stream_class *stream_class, + const char *name); + +/** +@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_ctf_stream_get_name(struct bt_ctf_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_ctf_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} +@postsuccessrefcountretinc +*/ +extern struct bt_ctf_stream_class *bt_ctf_stream_get_class( + struct bt_ctf_stream *stream); + +/** @} */ #ifdef __cplusplus }