5f0fd26bfda28c1522f946ce7cec5136032c2fab
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
34 #include <babeltrace/ref.h>
42 struct bt_stream_class
;
45 @defgroup ctfirstream CTF IR stream
50 #include <babeltrace/ctf-ir/stream.h>
54 See \ref ctfwriterstream which documents additional CTF IR stream
55 functions exclusive to the CTF writer mode.
57 A CTF IR <strong><em>stream</em></strong> is an instance of a
58 \link ctfirstreamclass CTF IR stream class\endlink.
60 You can obtain a CTF IR stream object in two different modes:
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().
71 A CTF IR stream object represents a CTF stream, that is, a sequence of
72 packets containing events:
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.
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.
90 @brief CTF IR stream type and functions.
93 @addtogroup ctfirstream
99 @brief A CTF IR stream.
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.
110 \p stream_class \em must have a parent
111 \link ctfirtraceclass CTF IR trace class\endlink.
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().
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 @param[in] id ID of the stream object to create.
123 @returns Created stream object, or \c NULL on error.
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
130 extern struct bt_stream
*bt_stream_create(struct bt_stream_class
*stream_class
,
131 const char *name
, uint64_t id
);
134 @brief Returns the name of the CTF IR stream \p stream.
136 On success, \p stream remains the sole owner of the returned string.
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.
143 @postrefcountsame{stream}
145 extern const char *bt_stream_get_name(struct bt_stream
*stream
);
148 @brief Returns the numeric ID of the CTF IR stream \p stream.
150 @param[in] stream Stream of which to get the numeric ID.
151 @returns ID of stream \p stream, or a negative value
155 @postrefcountsame{stream}
157 extern int64_t bt_stream_get_id(struct bt_stream
*stream
);
159 extern struct bt_stream_class
*bt_stream_borrow_class(
160 struct bt_stream
*stream
);
163 @brief Returns the parent CTF IR stream class of the CTF IR
166 This function returns a reference to the stream class which was used
167 to create the stream object in the first place with
170 @param[in] stream Stream of which to get the parent stream class.
171 @returns Parent stream class of \p stream,
175 @postrefcountsame{stream}
176 @postsuccessrefcountretinc
179 struct bt_stream_class
*bt_stream_get_class(
180 struct bt_stream
*stream
)
182 return bt_get(bt_stream_borrow_class(stream
));
191 #endif /* BABELTRACE_CTF_IR_STREAM_H */
This page took 0.033605 seconds and 4 git commands to generate.