include/babeltrace/ctf-ir/stream.h

   1 #ifndef BABELTRACE_CTF_IR_STREAM_H
   2 #define BABELTRACE_CTF_IR_STREAM_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <stdint.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 struct bt_stream_class;
  40
  41 /**
  42 @defgroup ctfirstream CTF IR stream
  43 @ingroup ctfir
  44 @brief CTF IR stream.
  45
  46 @code
  47 #include <babeltrace/ctf-ir/stream.h>
  48 @endcode
  49
  50 @note
  51 See \ref ctfwriterstream which documents additional CTF IR stream
  52 functions exclusive to the CTF writer mode.
  53
  54 A CTF IR <strong><em>stream</em></strong> is an instance of a
  55 \link ctfirstreamclass CTF IR stream class\endlink.
  56
  57 You can obtain a CTF IR stream object in two different modes:
  58
  59 - <strong>Normal mode</strong>: use bt_stream_create() or
  60   bt_stream_create_with_id() with a stream class having a
  61   \link ctfirtraceclass CTF IR trace class\endlink parent
  62   \em not created by a \link ctfwriter CTF writer\endlink object to
  63   create a default stream.
  64 - <strong>CTF writer mode</strong>: use bt_stream_create() with
  65   a stream class having a trace class parent created by a CTF writer
  66   object, or use bt_writer_create_stream().
  67
  68 A CTF IR stream object represents a CTF stream, that is, a sequence of
  69 packets containing events:
  70
  71 @imgtracestructure
  72
  73 A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
  74 IR packet\endlink objects: it only acts as a common parent to identify
  75 the original CTF stream of packet objects.
  76
  77 As with any Babeltrace object, CTF IR stream objects have
  78 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  79 counts</a>. See \ref refs to learn more about the reference counting
  80 management of Babeltrace objects.
  81
  82 @sa ctfirstreamclass
  83 @sa ctfirpacket
  84 @sa ctfwriterstream
  85
  86 @file
  87 @brief CTF IR stream type and functions.
  88 @sa ctfirstream
  89
  90 @addtogroup ctfirstream
  91 @{
  92 */
  93
  94 /**
  95 @struct bt_stream
  96 @brief A CTF IR stream.
  97 @sa ctfirstream
  98 @sa ctfwriterstream
  99 */
 100 struct bt_stream;
 101 struct bt_event;
 102
 103 /**
 104 @brief  Creates a default CTF IR stream named \p name from the CTF IR
 105         stream class \p stream_class.
 106
 107 \p stream_class \em must have a parent
 108 \link ctfirtraceclass CTF IR trace class\endlink.
 109
 110 If the parent \link ctfirtraceclass trace class\endlink of
 111 \p stream_class was created by a \link ctfwriter CTF writer\endlink
 112 object, then the stream object is created in CTF writer mode, and
 113 you can use the functions of \ref ctfwriterstream on it.
 114 Otherwise it is created in normal mode: you should only use the
 115 functions documented in this module on it.
 116
 117 \p name can be \c NULL to create an unnamed stream object.
 118
 119 @param[in] stream_class CTF IR stream class to use to create the
 120                         CTF IR stream.
 121 @param[in] name         Name of the stream object to create (copied on
 122                         success) or \c NULL to create an unnamed stream.
 123 @returns                Created stream object, or \c NULL on error.
 124
 125 @prenotnull{stream_class}
 126 @pre \p stream_class has a parent trace class.
 127 @postsuccessrefcountret1
 128
 129 @sa bt_stream_create_with_id(): Create a CTF IR stream with a
 130         specific ID.
 131 */
 132 extern struct bt_stream *bt_stream_create(
 133                 struct bt_stream_class *stream_class,
 134                 const char *name);
 135
 136 /**
 137 @brief  Creates a default CTF IR stream named \p name with ID \p id
 138         from the CTF IR stream class \p stream_class.
 139
 140 \p stream_class \em must have a parent
 141 \link ctfirtraceclass CTF IR trace class\endlink.
 142
 143 You \em must have created the trace class of \p stream class directly
 144 with bt_trace_create(), not through bt_writer_create() (use
 145 bt_stream_create() for this).
 146
 147 \p id \em must be unique amongst the IDs of all the streams created
 148 from \p stream_class with bt_stream_create_with_id().
 149
 150 \p name can be \c NULL to create an unnamed stream object.
 151
 152 @param[in] stream_class CTF IR stream class to use to create the
 153                         CTF IR stream.
 154 @param[in] name         Name of the stream object to create (copied on
 155                         success) or \c NULL to create an unnamed stream.
 156 @param[in] id           ID of the stream object to create.
 157 @returns                Created stream object, or \c NULL on error.
 158
 159 @prenotnull{stream_class}
 160 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 161 @pre \p stream_class has a parent trace class.
 162 @postsuccessrefcountret1
 163
 164 @sa bt_stream_create(): Create a CTF IR stream without an ID.
 165 */
 166 extern struct bt_stream *bt_stream_create_with_id(
 167                 struct bt_stream_class *stream_class,
 168                 const char *name, uint64_t id);
 169
 170 /**
 171 @brief  Returns the name of the CTF IR stream \p stream.
 172
 173 On success, \p stream remains the sole owner of the returned string.
 174
 175 @param[in] stream       Stream object of which to get the name.
 176 @returns                Name of stream \p stream, or \c NULL if
 177                         \p stream is unnamed or on error.
 178
 179 @prenotnull{stream}
 180 @postrefcountsame{stream}
 181 */
 182 extern const char *bt_stream_get_name(struct bt_stream *stream);
 183
 184 /**
 185 @brief  Returns the numeric ID of the CTF IR stream \p stream.
 186
 187 @param[in] stream       Stream of which to get the numeric ID.
 188 @returns                ID of stream \p stream, or a negative value
 189                         on error.
 190
 191 @prenotnull{stream}
 192 @postrefcountsame{stream}
 193 */
 194 extern int64_t bt_stream_get_id(struct bt_stream *stream);
 195
 196 /**
 197 @brief  Returns the parent CTF IR stream class of the CTF IR
 198         stream \p stream.
 199
 200 This function returns a reference to the stream class which was used
 201 to create the stream object in the first place with
 202 bt_stream_create().
 203
 204 @param[in] stream       Stream of which to get the parent stream class.
 205 @returns                Parent stream class of \p stream,
 206                         or \c NULL on error.
 207
 208 @prenotnull{stream}
 209 @postrefcountsame{stream}
 210 @postsuccessrefcountretinc
 211 */
 212 extern struct bt_stream_class *bt_stream_get_class(
 213                 struct bt_stream *stream);
 214
 215 /** @} */
 216
 217 /* Pre-2.0 CTF writer compatibility */
 218 #define bt_ctf_stream bt_stream
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* BABELTRACE_CTF_IR_STREAM_H */