140970c5aed86924216a7da48c52d64b9009b625
1 #ifndef BABELTRACE_CTF_IR_STREAM_H
2 #define BABELTRACE_CTF_IR_STREAM_H
5 * BabelTrace - CTF IR: Stream
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
33 #include <babeltrace/ctf-ir/stream-class.h>
41 @defgroup ctfirstream CTF IR stream
46 #include <babeltrace/ctf-ir/stream.h>
50 See \ref ctfwriterstream which documents additional CTF IR stream
51 functions exclusive to the CTF writer mode.
53 A CTF IR <strong><em>stream</em></strong> is an instance of a
54 \link ctfirstreamclass CTF IR stream class\endlink.
56 You can obtain a CTF IR stream object in two different modes:
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().
67 A CTF IR stream object represents a CTF stream, that is, a sequence of
68 packets containing events:
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.
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.
86 @brief CTF IR stream type and functions.
89 @addtogroup ctfirstream
95 @brief A CTF IR stream.
103 @brief Creates a default CTF IR stream named \p name from the CTF IR
104 stream class \p stream_class.
106 \p stream_class \em must have a parent
107 \link ctfirtraceclass CTF IR trace class\endlink.
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.
116 \p name can be \c NULL to create an unnamed stream object.
118 @param[in] stream_class CTF IR stream class to use to create the
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.
124 @prenotnull{stream_class}
125 @pre \p stream_class has a parent trace class.
126 @postsuccessrefcountret1
128 @sa bt_ctf_stream_create_with_id(): Create a CTF IR stream with a
131 extern struct bt_ctf_stream
*bt_ctf_stream_create(
132 struct bt_ctf_stream_class
*stream_class
,
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.
139 \p stream_class \em must have a parent
140 \link ctfirtraceclass CTF IR trace class\endlink.
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).
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().
149 \p name can be \c NULL to create an unnamed stream object.
151 @param[in] stream_class CTF IR stream class to use to create the
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.
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
163 @sa bt_ctf_stream_create(): Create a CTF IR stream without an ID.
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
);
170 @brief Returns the name of the CTF IR stream \p stream.
172 On success, \p stream remains the sole owner of the returned string.
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.
179 @postrefcountsame{stream}
181 extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream
*stream
);
184 @brief Returns the numeric ID of the CTF IR stream \p stream.
186 @param[in] stream Stream of which to get the numeric ID.
187 @returns ID of stream \p stream, or a negative value
191 @postrefcountsame{stream}
193 extern int64_t bt_ctf_stream_get_id(struct bt_ctf_stream
*stream
);
196 @brief Returns the parent CTF IR stream class of the CTF IR
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().
203 @param[in] stream Stream of which to get the parent stream class.
204 @returns Parent stream class of \p stream,
208 @postrefcountsame{stream}
209 @postsuccessrefcountretinc
211 extern struct bt_ctf_stream_class
*bt_ctf_stream_get_class(
212 struct bt_ctf_stream
*stream
);
220 #endif /* BABELTRACE_CTF_IR_STREAM_H */
This page took 0.035235 seconds and 4 git commands to generate.