X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Ftrace-ir%2Fstream.h;h=32bc98e1770decbad7e3db38da584a301d896899;hp=416e42cec15c4c128d09a97622f80846b579fdb1;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9

diff --git a/include/babeltrace2/trace-ir/stream.h b/include/babeltrace2/trace-ir/stream.h
index 416e42ce..32bc98e1 100644
--- a/include/babeltrace2/trace-ir/stream.h
+++ b/include/babeltrace2/trace-ir/stream.h
@@ -35,30 +35,631 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-stream Stream
+@ingroup api-tir
+
+@brief
+    Trace stream.
+
+A <strong><em>stream</em></strong> is a conceptual
+\ref api-msg-seq "sequence of messages" within a \bt_trace:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual sequence of \bt_p_msg.
+
+  The sequence always starts with a \bt_sb_msg and ends with a
+  \bt_se_msg.
+
+- A stream is an instance of a \bt_stream_cls.
+
+- A \bt_trace contains one or more streams.
+
+A stream is a \ref api-tir "trace IR" data object.
+
+A stream is said to be a \em conceptual sequence of messages because the
+stream object itself does not contain messages: it only represents a
+common timeline to which messages are associated.
+
+\bt_cp_comp exchange messages, within a trace processing \bt_graph,
+which can belong to different streams, as long as the stream clocks are
+\ref api-tir-clock-cls-origin "correlatable".
+
+A typical use case for streams is to use one for each traced CPU. Then
+the messages related to a given stream are the ones which occured on a
+given CPU. Other schemes are possible: they are completely
+application-specific, and \bt_name does not enforce any specific
+stream arrangement pattern.
+
+A \bt_trace contains streams. All the streams of a
+given trace, for a given stream class, have unique numeric IDs. Borrow
+the trace which contains a stream with bt_stream_borrow_trace() or
+bt_stream_borrow_trace_const().
+
+A \bt_stream can conceptually contain a default clock if its class
+has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+There's no function to access a stream's default clock because it's
+a stateful object: \bt_p_msg cannot refer to stateful objects
+because they must not change while being transported from one
+\bt_comp to the other. Instead of having a stream default clock object,
+\bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
+stream's default clock (a \bt_clock_cls instance):
+
+@image html clocks.png
+
+In the illustration above, notice that:
+
+- Streams (horizontal blue rectangles) are instances of a
+  \bt_stream_cls (orange).
+
+- A stream class has a default \bt_clock_cls (orange bell alarm clock).
+
+- Each stream has a default clock (yellow bell alarm clock): this is an
+  instance of the stream's class's default clock class.
+
+- Each \bt_msg (objects in blue stream rectangles) created for a given
+  stream has a default \bt_cs (yellow star): this is a snapshot of the
+  stream's default clock.
+
+  In other words, a default clock snapshot contains the value of the
+  stream's default clock when this message occured.
+
+To create a stream:
+
+<dl>
+  <dt>
+    If bt_stream_class_assigns_automatic_stream_id() returns
+    #BT_TRUE (the default) for the stream class to use
+  </dt>
+  <dd>Use bt_stream_create().</dd>
+
+  <dt>
+    If bt_stream_class_assigns_automatic_stream_id() returns
+    #BT_FALSE for the stream class to use
+  </dt>
+  <dd>Use bt_stream_create_with_id().</dd>
+</dl>
+
+A stream is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_stream_get_ref() and put an existing
+reference with bt_stream_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" streams on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of a stream is #bt_stream.
+
+<h1>Properties</h1>
+
+A stream has the following property:
+
+<dl>
+  <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
+  <dd>
+    Numeric ID, unique amongst the numeric IDs of the stream's
+    \bt_trace's streams for a given \bt_stream_cls. In other words,
+    two streams which belong to the same trace can have the same numeric
+    ID if they aren't instances of the same class.
+
+    Depending on whether or not the stream's class
+    automatically assigns stream IDs
+    (see bt_stream_class_assigns_automatic_stream_id()),
+    set the stream's numeric ID on creation with
+    bt_stream_create() or bt_stream_create_with_id().
+
+    You cannot change the numeric ID once the stream is created.
+
+    Get a stream's numeric ID with bt_stream_get_id().
+  </dd>
+
+  <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
+  <dd>
+    Name of the stream.
+
+    Use bt_stream_set_name() and bt_stream_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the stream.
+
+    User attributes are custom attributes attached to a stream.
+
+    Use bt_stream_set_user_attributes(),
+    bt_stream_borrow_user_attributes(), and
+    bt_stream_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_stream bt_stream;
+
+@brief
+    Stream.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
+    adds it to the \bt_trace \bt_p{trace}.
+
+This function instantiates \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_stream_id(stream_class)
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use bt_stream_create_with_id().
+    @endparblock
+
+On success, the returned stream has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-prop-id "Numeric ID"
+    <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
+  <tr>
+    <td>\ref api-tir-stream-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class from which to create the stream.
+@param[in] trace
+    Trace to add the created stream to.
+
+@returns
+    New stream reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
+    returns #BT_TRUE.
+@bt_pre_not_null{trace}
+
+@bt_post_success_frozen{stream_class}
+@bt_post_success_frozen{trace}
+
+@sa bt_stream_create_with_id() &mdash;
+    Creates a stream with a specific numeric ID and adds it to a
+    trace.
+*/
 extern bt_stream *bt_stream_create(bt_stream_class *stream_class,
 		bt_trace *trace);
 
+/*!
+@brief
+    Creates a stream with the numeric ID \bt_p{id}
+    from the \bt_stream_cls \bt_p{stream_class} and adds
+    it to the \bt_trace \bt_p{trace}.
+
+This function instantiates \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_stream_id(stream_class)
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use bt_stream_create().
+    @endparblock
+
+On success, the returned stream has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-prop-id "Numeric ID"
+    <td>\bt_p{id}
+  <tr>
+    <td>\ref api-tir-stream-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class from which to create the stream.
+@param[in] trace
+    Trace to add the created stream to.
+@param[in] id
+    Numeric ID of the stream to create and add to \bt_p{trace}.
+
+@returns
+    New stream reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
+    returns #BT_FALSE.
+@bt_pre_not_null{trace}
+@pre
+    \bt_p{trace} does not contain an instance of \bt_p{stream_class}
+    with the numeric ID \bt_p{id}.
+
+@bt_post_success_frozen{stream_class}
+@bt_post_success_frozen{trace}
+
+@sa bt_stream_create() &mdash;
+    Creates a stream with an automatic numeric ID and adds it to a
+    trace.
+*/
 extern bt_stream *bt_stream_create_with_id(
 		bt_stream_class *stream_class,
 		bt_trace *trace, uint64_t id);
 
-extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream);
+/*! @} */
 
-extern void bt_stream_set_user_attributes(
-		bt_stream *stream, const bt_value *user_attributes);
+/*!
+@name Class access
+@{
+*/
 
-extern bt_trace *bt_stream_borrow_trace(bt_stream *stream);
+/*!
+@brief
+    Borrows the \ref api-tir-stream-cls "class" of the stream
+    \bt_p{stream}.
+
+@param[in] stream
+    Stream of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
 
+@sa bt_stream_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream_class *bt_stream_borrow_class(bt_stream *stream);
 
+/*!
+@brief
+    Borrows the \ref api-tir-stream-cls "class" of the stream
+    \bt_p{stream} (\c const version).
+
+See bt_stream_borrow_class().
+*/
+extern const bt_stream_class *bt_stream_borrow_class_const(
+		const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Trace access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_trace which contains the stream \bt_p{stream}.
+
+@param[in] stream
+    Stream of which to borrow the trace containing it.
+
+@returns
+    \em Borrowed reference of the trace containing \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_borrow_trace_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_trace *bt_stream_borrow_trace(bt_stream *stream);
+
+/*!
+@brief
+    Borrows the \bt_trace which contains the stream \bt_p{stream}
+    (\c const version).
+
+See bt_stream_borrow_trace().
+*/
+extern const bt_trace *bt_stream_borrow_trace_const(
+		const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the numeric ID of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-id "numeric ID" property.
+
+@param[in] stream
+    Stream of which to get the numeric ID.
+
+@returns
+    Numeric ID of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_create_with_id() &mdash;
+    Creates a stream with a specific numeric ID and adds it to a
+    trace.
+*/
+extern uint64_t bt_stream_get_id(const bt_stream *stream);
+
+/*!
+@brief
+    Status codes for bt_stream_set_name().
+*/
 typedef enum bt_stream_set_name_status {
-	BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_STREAM_SET_NAME_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
+	BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_stream_set_name_status;
 
+/*!
+@brief
+    Sets the name of the stream \bt_p{stream} to
+    a copy of \bt_p{name}.
+
+See the \ref api-tir-stream-prop-name "name" property.
+
+@param[in] stream
+    Stream of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{stream} (copied).
+
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{stream}
+@bt_pre_hot{stream}
+@bt_pre_not_null{name}
+
+@sa bt_stream_get_name() &mdash;
+    Returns the name of a stream.
+*/
 extern bt_stream_set_name_status bt_stream_set_name(bt_stream *stream,
 		const char *name);
 
+/*!
+@brief
+    Returns the name of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-name "name" property.
+
+If \bt_p{stream} has no name, this function returns \c NULL.
+
+@param[in] stream
+    Stream of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{stream}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{stream}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_class_set_name() &mdash;
+    Sets the name of a stream.
+*/
+extern const char *bt_stream_get_name(const bt_stream *stream);
+
+/*!
+@brief
+    Sets the user attributes of the stream \bt_p{stream} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-stream-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream with bt_stream_create()
+    or bt_stream_create_with_id(), the stream's initial user
+    attributes is an empty \bt_map_val. Therefore you can borrow it with
+    bt_stream_borrow_user_attributes() and fill it directly
+    instead of setting a new one with this function.
+
+@param[in] stream
+    Stream of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+@bt_pre_hot{stream}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_stream_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a stream.
+*/
+extern void bt_stream_set_user_attributes(
+		bt_stream *stream, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream with bt_stream_create()
+    or bt_stream_create_with_id(), the stream's initial user
+    attributes is an empty \bt_map_val.
+
+@param[in] stream
+    Stream from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{stream} (a \bt_map_val).
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_set_user_attributes() &mdash;
+    Sets the user attributes of a stream.
+@sa bt_stream_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream);
+
+/*!
+@brief
+    Borrows the user attributes of the stream \bt_p{stream}
+    (\c const version).
+
+See bt_stream_borrow_user_attributes().
+*/
+extern const bt_value *bt_stream_borrow_user_attributes_const(
+		const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the stream \bt_p{stream}.
+
+@param[in] stream
+    @parblock
+    Stream of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_put_ref() &mdash;
+    Decrements the reference count of a stream.
+*/
+extern void bt_stream_get_ref(const bt_stream *stream);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the stream \bt_p{stream}.
+
+@param[in] stream
+    @parblock
+    Stream of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_get_ref() &mdash;
+    Increments the reference count of a stream.
+*/
+extern void bt_stream_put_ref(const bt_stream *stream);
+
+/*!
+@brief
+    Decrements the reference count of the stream
+    \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
+
+@param _stream
+    @parblock
+    Stream of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_stream}
+*/
+#define BT_STREAM_PUT_REF_AND_RESET(_stream)		\
+	do {						\
+		bt_stream_put_ref(_stream);		\
+		(_stream) = NULL;			\
+	} while (0)
+
+/*!
+@brief
+    Decrements the reference count of the stream \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a stream reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_STREAM_MOVE_REF(_dst, _src)		\
+	do {					\
+		bt_stream_put_ref(_dst);	\
+		(_dst) = (_src);		\
+		(_src) = NULL;			\
+	} while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif