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