From: Philippe Proulx Date: Tue, 22 Nov 2016 20:35:41 +0000 (-0500) Subject: Document stream.h (API) X-Git-Tag: v2.0.0-pre1~677 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=54f61f03e8dc0f9271b1c5e992bb95d69b2a4b6f Document stream.h (API) Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in index 3c259176..9b8c1edc 100644 --- a/doc/api/Doxyfile.in +++ b/doc/api/Doxyfile.in @@ -25,6 +25,7 @@ ALIASES += postsuccessrefcountretinc="@post On successOn success, the reference count of the returned object is 1." ALIASES += postsuccessrefcountinc{1}="@post On success, the reference count of \p \1 is incremented." ALIASES += postrefcountsame{1}="@post The reference count of \p \1 is not modified." +ALIASES += postsuccessfrozen{1}="@post On success, \p \1 is frozen." ALIASES += prenotnull{1}="@pre \p \1 is not \c NULL." ALIASES += prehot{1}="@pre \p \1 is not frozen." ALIASES += preisintft{1}="@pre \p \1 is a CTF IR integer field type." @@ -44,6 +45,7 @@ ALIASES += preisarrayfield{1}="@pre \p \1 is a CTF IR array field. ALIASES += preisseqfield{1}="@pre \p \1 is a CTF IR sequence field." ALIASES += preisvarfield{1}="@pre \p \1 is a CTF IR variant field." ALIASES += imgpacketstructure="@image html ctf-stream-packet.png \"Structure of a CTF packet.\"" +ALIASES += imgtracestructure="@image html ctf-trace.png \"Structure of a CTF trace.\"" OPTIMIZE_OUTPUT_FOR_C = YES MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 0 diff --git a/doc/api/images/ctf-trace.png b/doc/api/images/ctf-trace.png new file mode 100644 index 00000000..64a389c2 Binary files /dev/null and b/doc/api/images/ctf-trace.png differ diff --git a/include/babeltrace/ctf-ir/stream.h b/include/babeltrace/ctf-ir/stream.h index a08e327f..8de7e243 100644 --- a/include/babeltrace/ctf-ir/stream.h +++ b/include/babeltrace/ctf-ir/stream.h @@ -37,25 +37,121 @@ extern "C" { #endif -struct bt_ctf_event; +/** +@defgroup ctfirstream CTF IR stream +@ingroup ctfir +@brief CTF IR stream. + +@note +See \ref ctfirwriterstream which documents additional CTF IR stream +functions exclusive to the CTF IR 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_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(). + +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 ctfirwriterstream + +@file +@brief CTF IR stream type and functions. +@sa ctfirstream + +@addtogroup ctfirstream +@{ +*/ + 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); -/* - * bt_ctf_stream_get_stream_class: get a stream's class. - * - * @param stream Stream instance. - * - * Returns the stream's class, NULL on error. - */ +/** +@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 } #endif