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 <babeltrace/ctf-ir/stream-class.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41 @defgroup ctfirstream CTF IR stream
  42 @ingroup ctfir
  43 @brief CTF IR stream.
  44
  45 @code
  46 #include <babeltrace/ctf-ir/stream.h>
  47 @endcode
  48
  49 @note
  50 See \ref ctfwriterstream which documents additional CTF IR stream
  51 functions exclusive to the CTF writer mode.
  52
  53 A CTF IR <strong><em>stream</em></strong> is an instance of a
  54 \link ctfirstreamclass CTF IR stream class\endlink.
  55
  56 You can obtain a CTF IR stream object in two different modes:
  57
  58 - <strong>Normal mode</strong>: use bt_ctf_stream_create() or
  59   bt_ctf_stream_create_with_id() with a stream class having a
  60   \link ctfirtraceclass CTF IR trace class\endlink parent
  61   \em not created by a \link ctfwriter CTF writer\endlink object to
  62   create a default stream.
  63 - <strong>CTF writer mode</strong>: use bt_ctf_stream_create() with
  64   a stream class having a trace class parent created by a CTF writer
  65   object, or use bt_ctf_writer_create_stream().
  66
  67 A CTF IR stream object represents a CTF stream, that is, a sequence of
  68 packets containing events:
  69
  70 @imgtracestructure
  71
  72 A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
  73 IR packet\endlink objects: it only acts as a common parent to identify
  74 the original CTF stream of packet objects.
  75
  76 As with any Babeltrace object, CTF IR stream objects have
  77 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  78 counts</a>. See \ref refs to learn more about the reference counting
  79 management of Babeltrace objects.
  80
  81 @sa ctfirstreamclass
  82 @sa ctfirpacket
  83 @sa ctfwriterstream
  84
  85 @file
  86 @brief CTF IR stream type and functions.
  87 @sa ctfirstream
  88
  89 @addtogroup ctfirstream
  90 @{
  91 */
  92
  93 /**
  94 @struct bt_ctf_stream
  95 @brief A CTF IR stream.
  96 @sa ctfirstream
  97 @sa ctfwriterstream
  98 */
  99 struct bt_ctf_stream;
 100 struct bt_ctf_event;
 101
 102 /**
 103 @brief  Creates a default CTF IR stream named \p name from the CTF IR
 104         stream class \p stream_class.
 105
 106 \p stream_class \em must have a parent
 107 \link ctfirtraceclass CTF IR trace class\endlink.
 108
 109 If the parent \link ctfirtraceclass trace class\endlink of
 110 \p stream_class was created by a \link ctfwriter CTF writer\endlink
 111 object, then the stream object is created in CTF writer mode, and
 112 you can use the functions of \ref ctfwriterstream on it.
 113 Otherwise it is created in normal mode: you should only use the
 114 functions documented in this module on it.
 115
 116 \p name can be \c NULL to create an unnamed stream object.
 117
 118 @param[in] stream_class CTF IR stream class to use to create the
 119                         CTF IR stream.
 120 @param[in] name         Name of the stream object to create (copied on
 121                         success) or \c NULL to create an unnamed stream.
 122 @returns                Created stream object, or \c NULL on error.
 123
 124 @prenotnull{stream_class}
 125 @pre \p stream_class has a parent trace class.
 126 @postsuccessrefcountret1
 127
 128 @sa bt_ctf_stream_create_with_id(): Create a CTF IR stream with a
 129         specific ID.
 130 */
 131 extern struct bt_ctf_stream *bt_ctf_stream_create(
 132                 struct bt_ctf_stream_class *stream_class,
 133                 const char *name);
 134
 135 /**
 136 @brief  Creates a default CTF IR stream named \p name with ID \p id
 137         from the CTF IR stream class \p stream_class.
 138
 139 \p stream_class \em must have a parent
 140 \link ctfirtraceclass CTF IR trace class\endlink.
 141
 142 You \em must have created the trace class of \p stream class directly
 143 with bt_ctf_trace_create(), not through bt_ctf_writer_create() (use
 144 bt_ctf_stream_create() for this).
 145
 146 \p id \em must be unique amongst the IDs of all the streams created
 147 from \p stream_class with bt_ctf_stream_create_with_id().
 148
 149 \p name can be \c NULL to create an unnamed stream object.
 150
 151 @param[in] stream_class CTF IR stream class to use to create the
 152                         CTF IR stream.
 153 @param[in] name         Name of the stream object to create (copied on
 154                         success) or \c NULL to create an unnamed stream.
 155 @param[in] id           ID of the stream object to create.
 156 @returns                Created stream object, or \c NULL on error.
 157
 158 @prenotnull{stream_class}
 159 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 160 @pre \p stream_class has a parent trace class.
 161 @postsuccessrefcountret1
 162
 163 @sa bt_ctf_stream_create(): Create a CTF IR stream without an ID.
 164 */
 165 extern struct bt_ctf_stream *bt_ctf_stream_create_with_id(
 166                 struct bt_ctf_stream_class *stream_class,
 167                 const char *name, uint64_t id);
 168
 169 /**
 170 @brief  Returns the name of the CTF IR stream \p stream.
 171
 172 On success, \p stream remains the sole owner of the returned string.
 173
 174 @param[in] stream       Stream object of which to get the name.
 175 @returns                Name of stream \p stream, or \c NULL if
 176                         \p stream is unnamed or on error.
 177
 178 @prenotnull{stream}
 179 @postrefcountsame{stream}
 180 */
 181 extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
 182
 183 /**
 184 @brief  Returns the numeric ID of the CTF IR stream \p stream.
 185
 186 @param[in] stream       Stream of which to get the numeric ID.
 187 @returns                ID of stream \p stream, or a negative value
 188                         on error.
 189
 190 @prenotnull{stream}
 191 @postrefcountsame{stream}
 192 */
 193 extern int64_t bt_ctf_stream_get_id(struct bt_ctf_stream *stream);
 194
 195 /**
 196 @brief  Returns the parent CTF IR stream class of the CTF IR
 197         stream \p stream.
 198
 199 This function returns a reference to the stream class which was used
 200 to create the stream object in the first place with
 201 bt_ctf_stream_create().
 202
 203 @param[in] stream       Stream of which to get the parent stream class.
 204 @returns                Parent stream class of \p stream,
 205                         or \c NULL on error.
 206
 207 @prenotnull{stream}
 208 @postrefcountsame{stream}
 209 @postsuccessrefcountretinc
 210 */
 211 extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
 212                 struct bt_ctf_stream *stream);
 213
 214 /** @} */
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif /* BABELTRACE_CTF_IR_STREAM_H */