1 #ifndef BABELTRACE_CTF_IR_EVENT_H
2 #define BABELTRACE_CTF_IR_EVENT_H
5 * BabelTrace - CTF IR: Event
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>
44 struct bt_clock_class
;
47 @defgroup ctfirevent CTF IR event
52 #include <babeltrace/ctf-ir/event.h>
55 A CTF IR <strong><em>event</em></strong> is a container of event
58 - <strong>Stream event header</strong> field, described by the
59 <em>stream event header field type</em> of a
60 \link ctfirstreamclass CTF IR stream class\endlink.
61 - <strong>Stream event context</strong> field, described by the
62 <em>stream event context field type</em> of a stream class.
63 - <strong>Event context</strong> field, described by the
64 <em>event context field type</em> of a
65 \link ctfireventclass CTF IR event class\endlink.
66 - <strong>Event payload</strong>, described by the
67 <em>event payload field type</em> of an event class.
69 As a reminder, here's the structure of a CTF packet:
73 You can create a CTF IR event \em from a
74 \link ctfireventclass CTF IR event class\endlink with
75 bt_event_create(). The event class you use to create an event
76 object becomes its parent.
78 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
79 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
80 which is the parent of its event class) was created by a
81 \link ctfwriter CTF writer\endlink object, then the only possible
82 action you can do with this event object is to append it to a
83 \link ctfirstream CTF IR stream\endlink with
84 bt_stream_append_event(). Otherwise, you can create an event
85 notification with bt_notification_event_create(). The event you pass
86 to this function \em must have an attached packet object first.
88 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
89 event object with bt_event_set_packet().
91 A CTF IR event has a mapping of
92 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
93 an instance of a specific
94 \link ctfirclockclass CTF IR clock class\endlink when the event is
95 emitted. You can set an event object's clock value with
96 bt_event_set_clock_value().
98 As with any Babeltrace object, CTF IR event objects have
99 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
100 counts</a>. See \ref refs to learn more about the reference counting
101 management of Babeltrace objects.
103 bt_notification_event_create() \em freezes its event parameter on
104 success. You cannot modify a frozen event object: it is considered
105 immutable, except for \link refs reference counting\endlink.
111 @brief CTF IR event type and functions.
114 @addtogroup ctfirevent
120 @brief A CTF IR event.
124 struct bt_event_header_field
;
126 struct bt_clock_value
;
127 struct bt_event_class
;
129 struct bt_field_type
;
130 struct bt_stream_class
;
134 @name Creation and parent access functions
139 @brief Creates a default CTF IR event from the CTF IR event class
142 \p event_class \em must have a parent
143 \link ctfirstreamclass CTF IR stream class\endlink.
145 On success, the four fields of the created event object are not set. You
146 can set them with bt_event_set_header(),
147 bt_event_set_stream_event_context(),
148 bt_event_set_context(), and bt_event_set_payload().
150 This function tries to resolve the needed
151 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
152 types that are found anywhere in the context or payload field
153 types of \p event_class and in the root field types of the
154 parent stream class of \p event_class. If any automatic resolving fails,
155 this function fails. This means that, if any dynamic field type need
156 a field type which should be found in the trace packet header root
157 field type, and if the parent stream class of \p event_class was not
158 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
159 with bt_trace_add_stream_class(), then this function fails.
161 @param[in] event_class CTF IR event class to use to create the
163 @returns Created event object, or \c NULL on error.
165 @prenotnull{event_class}
166 @pre \p event_class has a parent stream class.
167 @postsuccessrefcountret1
169 extern struct bt_event_class
*bt_event_borrow_class(struct bt_event
*event
);
172 @brief Returns the parent CTF IR event class of the CTF IR event
175 This function returns a reference to the event class which was used to
176 create the event object in the first place with bt_event_create().
178 @param[in] event Event of which to get the parent event class.
179 @returns Parent event class of \p event,
183 @postrefcountsame{event}
184 @postsuccessrefcountretinc
187 struct bt_event_class
*bt_event_get_class(struct bt_event
*event
)
189 return bt_get(bt_event_borrow_class(event
));
192 extern struct bt_packet
*bt_event_borrow_packet(struct bt_event
*event
);
195 @brief Returns the CTF IR packet associated to the CTF IR event
198 This function returns a reference to the event class which was set to
199 \p event in the first place with bt_event_set_packet().
201 @param[in] event Event of which to get the associated packet.
202 @returns Packet associated to \p event,
203 or \c NULL if no packet is associated to
204 \p event or on error.
207 @postrefcountsame{event}
208 @postsuccessrefcountretinc
210 @sa bt_event_set_packet(): Associates a given event to a given
214 struct bt_packet
*bt_event_get_packet(struct bt_event
*event
)
216 return bt_get(bt_event_borrow_packet(event
));
219 extern struct bt_stream
*bt_event_borrow_stream(struct bt_event
*event
);
222 @brief Returns the parent CTF IR stream associated to the CTF IR event
225 @param[in] event Event of which to get the parent stream.
226 @returns Parent stream of \p event, or \c NULL on error.
229 @postrefcountsame{event}
230 @postsuccessrefcountretinc
233 struct bt_stream
*bt_event_get_stream(struct bt_event
*event
)
235 return bt_get(bt_event_borrow_stream(event
));
241 @name Contained fields functions
245 extern struct bt_field
*bt_event_borrow_header(struct bt_event
*event
);
247 extern int bt_event_move_header(struct bt_event
*event
,
248 struct bt_event_header_field
*header
);
250 extern struct bt_field
*bt_event_borrow_stream_event_context(
251 struct bt_event
*event
);
253 extern struct bt_field
*bt_event_borrow_context(struct bt_event
*event
);
255 extern struct bt_field
*bt_event_borrow_payload(struct bt_event
*event
);
260 @name Clock value functions
264 extern struct bt_clock_value
*bt_event_borrow_clock_value(
265 struct bt_event
*event
,
266 struct bt_clock_class
*clock_class
);
276 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.035188 seconds and 4 git commands to generate.