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 with ID \p id
 105         from the CTF IR 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 \p id \em must be unique amongst the IDs of all the streams created
 111 from \p stream_class with bt_stream_create_with_id().
 112
 113 \p name can be \c NULL to create an unnamed stream object.
 114
 115 @param[in] stream_class CTF IR stream class to use to create the
 116                         CTF IR stream.
 117 @param[in] name         Name of the stream object to create (copied on
 118                         success) or \c NULL to create an unnamed stream.
 119 @param[in] id           ID of the stream object to create.
 120 @returns                Created stream object, or \c NULL on error.
 121
 122 @prenotnull{stream_class}
 123 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 124 @pre \p stream_class has a parent trace class.
 125 @postsuccessrefcountret1
 126 */
 127 extern struct bt_stream *bt_stream_create(struct bt_stream_class *stream_class,
 128                 const char *name, uint64_t id);
 129
 130 /**
 131 @brief  Returns the name of the CTF IR stream \p stream.
 132
 133 On success, \p stream remains the sole owner of the returned string.
 134
 135 @param[in] stream       Stream object of which to get the name.
 136 @returns                Name of stream \p stream, or \c NULL if
 137                         \p stream is unnamed or on error.
 138
 139 @prenotnull{stream}
 140 @postrefcountsame{stream}
 141 */
 142 extern const char *bt_stream_get_name(struct bt_stream *stream);
 143
 144 /**
 145 @brief  Returns the numeric ID of the CTF IR stream \p stream.
 146
 147 @param[in] stream       Stream of which to get the numeric ID.
 148 @returns                ID of stream \p stream, or a negative value
 149                         on error.
 150
 151 @prenotnull{stream}
 152 @postrefcountsame{stream}
 153 */
 154 extern int64_t bt_stream_get_id(struct bt_stream *stream);
 155
 156 /**
 157 @brief  Returns the parent CTF IR stream class of the CTF IR
 158         stream \p stream.
 159
 160 This function returns a reference to the stream class which was used
 161 to create the stream object in the first place with
 162 bt_stream_create().
 163
 164 @param[in] stream       Stream of which to get the parent stream class.
 165 @returns                Parent stream class of \p stream,
 166                         or \c NULL on error.
 167
 168 @prenotnull{stream}
 169 @postrefcountsame{stream}
 170 @postsuccessrefcountretinc
 171 */
 172 extern struct bt_stream_class *bt_stream_get_class(
 173                 struct bt_stream *stream);
 174
 175 /** @} */
 176
 177 #ifdef __cplusplus
 178 }
 179 #endif
 180
 181 #endif /* BABELTRACE_CTF_IR_STREAM_H */