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>
37 #include <babeltrace/types.h>
47 struct bt_clock_class
;
50 @defgroup ctfirevent CTF IR event
55 #include <babeltrace/ctf-ir/event.h>
58 A CTF IR <strong><em>event</em></strong> is a container of event
61 - <strong>Stream event header</strong> field, described by the
62 <em>stream event header field type</em> of a
63 \link ctfirstreamclass CTF IR stream class\endlink.
64 - <strong>Stream event context</strong> field, described by the
65 <em>stream event context field type</em> of a stream class.
66 - <strong>Event context</strong> field, described by the
67 <em>event context field type</em> of a
68 \link ctfireventclass CTF IR event class\endlink.
69 - <strong>Event payload</strong>, described by the
70 <em>event payload field type</em> of an event class.
72 As a reminder, here's the structure of a CTF packet:
76 You can create a CTF IR event \em from a
77 \link ctfireventclass CTF IR event class\endlink with
78 bt_event_create(). The event class you use to create an event
79 object becomes its parent.
81 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
82 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
83 which is the parent of its event class) was created by a
84 \link ctfwriter CTF writer\endlink object, then the only possible
85 action you can do with this event object is to append it to a
86 \link ctfirstream CTF IR stream\endlink with
87 bt_stream_append_event(). Otherwise, you can create an event
88 notification with bt_notification_event_create(). The event you pass
89 to this function \em must have an attached packet object first.
91 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
92 event object with bt_event_set_packet().
94 A CTF IR event has a mapping of
95 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
96 an instance of a specific
97 \link ctfirclockclass CTF IR clock class\endlink when the event is
98 emitted. You can set an event object's clock value with
99 bt_event_set_clock_value().
101 As with any Babeltrace object, CTF IR event objects have
102 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
103 counts</a>. See \ref refs to learn more about the reference counting
104 management of Babeltrace objects.
106 bt_notification_event_create() \em freezes its event parameter on
107 success. You cannot modify a frozen event object: it is considered
108 immutable, except for \link refs reference counting\endlink.
114 @brief CTF IR event type and functions.
117 @addtogroup ctfirevent
123 @brief A CTF IR event.
127 struct bt_event_header_field
;
129 struct bt_clock_value
;
130 struct bt_event_class
;
132 struct bt_field_type
;
133 struct bt_stream_class
;
137 @name Creation and parent access functions
142 @brief Creates a default CTF IR event from the CTF IR event class
145 \p event_class \em must have a parent
146 \link ctfirstreamclass CTF IR stream class\endlink.
148 On success, the four fields of the created event object are not set. You
149 can set them with bt_event_set_header(),
150 bt_event_set_stream_event_context(),
151 bt_event_set_context(), and bt_event_set_payload().
153 This function tries to resolve the needed
154 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
155 types that are found anywhere in the context or payload field
156 types of \p event_class and in the root field types of the
157 parent stream class of \p event_class. If any automatic resolving fails,
158 this function fails. This means that, if any dynamic field type need
159 a field type which should be found in the trace packet header root
160 field type, and if the parent stream class of \p event_class was not
161 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
162 with bt_trace_add_stream_class(), then this function fails.
164 @param[in] event_class CTF IR event class to use to create the
166 @returns Created event object, or \c NULL on error.
168 @prenotnull{event_class}
169 @pre \p event_class has a parent stream class.
170 @postsuccessrefcountret1
172 extern struct bt_event_class
*bt_event_borrow_class(struct bt_event
*event
);
175 @brief Returns the parent CTF IR event class of the CTF IR event
178 This function returns a reference to the event class which was used to
179 create the event object in the first place with bt_event_create().
181 @param[in] event Event of which to get the parent event class.
182 @returns Parent event class of \p event,
186 @postrefcountsame{event}
187 @postsuccessrefcountretinc
190 struct bt_event_class
*bt_event_get_class(struct bt_event
*event
)
192 return bt_get(bt_event_borrow_class(event
));
195 extern struct bt_packet
*bt_event_borrow_packet(struct bt_event
*event
);
198 @brief Returns the CTF IR packet associated to the CTF IR event
201 This function returns a reference to the event class which was set to
202 \p event in the first place with bt_event_set_packet().
204 @param[in] event Event of which to get the associated packet.
205 @returns Packet associated to \p event,
206 or \c NULL if no packet is associated to
207 \p event or on error.
210 @postrefcountsame{event}
211 @postsuccessrefcountretinc
213 @sa bt_event_set_packet(): Associates a given event to a given
217 struct bt_packet
*bt_event_get_packet(struct bt_event
*event
)
219 return bt_get(bt_event_borrow_packet(event
));
222 extern struct bt_stream
*bt_event_borrow_stream(struct bt_event
*event
);
225 @brief Returns the parent CTF IR stream associated to the CTF IR event
228 @param[in] event Event of which to get the parent stream.
229 @returns Parent stream of \p event, or \c NULL on error.
232 @postrefcountsame{event}
233 @postsuccessrefcountretinc
236 struct bt_stream
*bt_event_get_stream(struct bt_event
*event
)
238 return bt_get(bt_event_borrow_stream(event
));
244 @name Contained fields functions
248 extern struct bt_field
*bt_event_borrow_header(struct bt_event
*event
);
250 extern int bt_event_move_header(struct bt_event
*event
,
251 struct bt_event_header_field
*header
);
253 extern struct bt_field
*bt_event_borrow_stream_event_context(
254 struct bt_event
*event
);
256 extern struct bt_field
*bt_event_borrow_context(struct bt_event
*event
);
258 extern struct bt_field
*bt_event_borrow_payload(struct bt_event
*event
);
263 @name Clock value functions
267 extern int bt_event_set_clock_value(struct bt_event
*event
,
268 struct bt_clock_class
*clock_class
, uint64_t raw_value
,
271 extern struct bt_clock_value
*bt_event_borrow_default_clock_value(
272 struct bt_event
*event
);
282 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.0362 seconds and 5 git commands to generate.