+/*!
+@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 occurred 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 occurred.
+
+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() —
+ Creates a stream with a specific numeric ID and adds it to a
+ trace.
+*/