42d39269b46b68f2593c469ba8ba4b8890151d34
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
35 #include <babeltrace/values.h>
36 #include <babeltrace/ctf-ir/clock-class.h>
43 @defgroup ctfirevent CTF IR event
48 #include <babeltrace/ctf-ir/event.h>
51 A CTF IR <strong><em>event</em></strong> is a container of event
54 - <strong>Stream event header</strong> field, described by the
55 <em>stream event header field type</em> of a
56 \link ctfirstreamclass CTF IR stream class\endlink.
57 - <strong>Stream event context</strong> field, described by the
58 <em>stream event context field type</em> of a stream class.
59 - <strong>Event context</strong> field, described by the
60 <em>event context field type</em> of a
61 \link ctfireventclass CTF IR event class\endlink.
62 - <strong>Event payload</strong>, described by the
63 <em>event payload field type</em> of an event class.
65 As a reminder, here's the structure of a CTF packet:
69 You can create a CTF IR event \em from a
70 \link ctfireventclass CTF IR event class\endlink with
71 bt_ctf_event_create(). The event class you use to create an event
72 object becomes its parent.
74 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
75 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
76 which is the parent of its event class) was created by a
77 \link ctfwriter CTF writer\endlink object, then the only possible
78 action you can do with this event object is to append it to a
79 \link ctfirstream CTF IR stream\endlink with
80 bt_ctf_stream_append_event(). Otherwise, you can create an event
81 notification with bt_notification_event_create(). The event you pass
82 to this function \em must have an attached packet object first.
84 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
85 event object with bt_ctf_event_set_packet().
87 A CTF IR event has a mapping of
88 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
89 an instance of a specific
90 \link ctfirclockclass CTF IR clock class\endlink when the event is
91 emitted. You can set an event object's clock value with
92 bt_ctf_event_set_clock_value().
94 As with any Babeltrace object, CTF IR event objects have
95 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
96 counts</a>. See \ref refs to learn more about the reference counting
97 management of Babeltrace objects.
99 bt_notification_event_create() \em freezes its event parameter on
100 success. You cannot modify a frozen event object: it is considered
101 immutable, except for \link refs reference counting\endlink.
107 @brief CTF IR event type and functions.
110 @addtogroup ctfirevent
116 @brief A CTF IR event.
121 struct bt_ctf_clock_value
;
122 struct bt_ctf_event_class
;
124 struct bt_ctf_field_type
;
125 struct bt_ctf_stream_class
;
126 struct bt_ctf_packet
;
129 @name Creation and parent access functions
134 @brief Creates a default CTF IR event from the CTF IR event class
137 \p event_class \em must have a parent
138 \link ctfirstreamclass CTF IR stream class\endlink.
140 On success, the four fields of the created event object are not set. You
141 can set them with bt_ctf_event_set_header(),
142 bt_ctf_event_set_stream_event_context(),
143 bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field().
145 This function tries to resolve the needed
146 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
147 types that are found anywhere in the context or payload field
148 types of \p event_class and in the root field types of the
149 parent stream class of \p event_class. If any automatic resolving fails,
150 this function fails. This means that, if any dynamic field type need
151 a field type which should be found in the trace packet header root
152 field type, and if the parent stream class of \p event_class was not
153 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
154 with bt_ctf_trace_add_stream_class(), then this function fails.
156 @param[in] event_class CTF IR event class to use to create the
158 @returns Created event object, or \c NULL on error.
160 @prenotnull{event_class}
161 @pre \p event_class has a parent stream class.
162 @postsuccessrefcountret1
164 extern struct bt_ctf_event
*bt_ctf_event_create(
165 struct bt_ctf_event_class
*event_class
);
168 @brief Returns the parent CTF IR event class of the CTF IR event
171 This function returns a reference to the event class which was used to
172 create the event object in the first place with bt_ctf_event_create().
174 @param[in] event Event of which to get the parent event class.
175 @returns Parent event class of \p event,
179 @postrefcountsame{event}
180 @postsuccessrefcountretinc
182 extern struct bt_ctf_event_class
*bt_ctf_event_get_class(
183 struct bt_ctf_event
*event
);
186 @brief Returns the CTF IR packet associated to the CTF IR event
189 This function returns a reference to the event class which was set to
190 \p event in the first place with bt_ctf_event_set_packet().
192 @param[in] event Event of which to get the associated packet.
193 @returns Packet associated to \p event,
194 or \c NULL if no packet is associated to
195 \p event or on error.
198 @postrefcountsame{event}
199 @postsuccessrefcountretinc
201 @sa bt_ctf_event_set_packet(): Associates a given event to a given
204 extern struct bt_ctf_packet
*bt_ctf_event_get_packet(
205 struct bt_ctf_event
*event
);
208 @brief Associates the CTF IR event \p event to the CTF IR packet
211 The \link ctfirstreamclass CTF IR stream class\endlink of the
212 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
213 be the same as the parent stream class of the
214 \link ctfireventclass CTF IR event class\endlink returned
215 by bt_ctf_event_get_class() for \p event.
217 You \em must call this function to create an event-packet association
218 before you call bt_notification_event_create() with \p event.
220 On success, this function also sets the parent stream object of
221 \p event to the parent stream of \p packet.
223 @param[in] event Event to which to associate \p packet.
224 @param[in] packet Packet to associate to \p event.
225 @returns 0 on success, or a negative value on error.
230 @pre The parent stream class of \p packet is the same as the parent
231 stream class of \p event.
232 @postsuccessrefcountretinc
234 @sa bt_ctf_event_get_packet(): Returns the associated packet of a
237 extern int bt_ctf_event_set_packet(struct bt_ctf_event
*event
,
238 struct bt_ctf_packet
*packet
);
241 @brief Returns the parent CTF IR stream associated to the CTF IR event
244 @param[in] event Event of which to get the parent stream.
245 @returns Parent stream of \p event, or \c NULL on error.
248 @postrefcountsame{event}
249 @postsuccessrefcountretinc
251 extern struct bt_ctf_stream
*bt_ctf_event_get_stream(
252 struct bt_ctf_event
*event
);
257 @name Contained fields functions
262 @brief Returns the stream event header field of the CTF IR event
265 @param[in] event Event of which to get the stream event header
267 @returns Stream event header field of \p event,
268 or \c NULL if the stream event header
269 field is not set or on error.
272 @postrefcountsame{event}
273 @postsuccessrefcountretinc
275 @sa bt_ctf_event_get_header(): Sets the stream event header
276 field of a given event.
278 extern struct bt_ctf_field
*bt_ctf_event_get_header(
279 struct bt_ctf_event
*event
);
282 @brief Sets the stream event header field of the CTF IR event
283 \p event to \p header, or unsets the current stream event header field
286 If \p header is not \c NULL, the field type of \p header, as returned by
287 bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
288 bt_ctf_stream_class_get_event_header_type() for the parent stream class
291 @param[in] event Event of which to set the stream event header
293 @param[in] header Stream event header field.
294 @returns 0 on success, or a negative value on error.
298 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
299 the field type returned by bt_ctf_stream_class_get_event_header_type()
300 for the parent stream class of \p event.
301 @postrefcountsame{event}
302 @post <strong>On success, if \p header is not \c NULL</strong>,
303 the reference count of \p header is incremented.
305 @sa bt_ctf_event_get_header(): Returns the stream event header field
308 extern int bt_ctf_event_set_header(struct bt_ctf_event
*event
,
309 struct bt_ctf_field
*header
);
312 @brief Returns the stream event context field of the CTF IR event
315 @param[in] event Event of which to get the stream event context
317 @returns Stream event context field of \p event,
318 or \c NULL if the stream event context
319 field is not set or on error.
322 @postrefcountsame{event}
323 @postsuccessrefcountretinc
325 @sa bt_ctf_event_set_stream_event_context(): Sets the stream event context
326 field of a given event.
328 extern struct bt_ctf_field
*bt_ctf_event_get_stream_event_context(
329 struct bt_ctf_event
*event
);
332 @brief Sets the stream event context field of the CTF IR event
333 \p event to \p context, or unsets the current stream event context field
336 If \p context is not \c NULL, the field type of \p context, as returned by
337 bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
338 bt_ctf_stream_class_get_event_context_type() for the parent stream class
341 @param[in] event Event of which to set the stream event context field.
342 @param[in] context Stream event context field.
343 @returns 0 on success, or a negative value on error.
347 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
348 the field type returned by bt_ctf_stream_class_get_event_context_type()
349 for the parent stream class of \p event.
350 @postrefcountsame{event}
351 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
352 count of \p context is incremented.
354 @sa bt_ctf_event_get_stream_event_context(): Returns the stream event context
355 field of a given event.
357 extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event
*event
,
358 struct bt_ctf_field
*context
);
361 @brief Returns the event context field of the CTF IR event \p event.
363 @param[in] event Event of which to get the context field.
364 @returns Event context field of \p event, or \c NULL if the
365 event context field is not set or on error.
368 @postrefcountsame{event}
369 @postsuccessrefcountretinc
371 @sa bt_ctf_event_set_event_context(): Sets the event context field of a given
374 extern struct bt_ctf_field
*bt_ctf_event_get_event_context(
375 struct bt_ctf_event
*event
);
378 @brief Sets the event context field of the CTF IR event \p event to \p context,
379 or unsets the current event context field from \p event.
381 If \p context is not \c NULL, the field type of \p context, as returned by
382 bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
383 bt_ctf_event_class_get_context_type() for the parent class of \p event.
385 @param[in] event Event of which to set the context field.
386 @param[in] context Event context field.
387 @returns 0 on success, or a negative value on error.
391 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
392 the field type returned by bt_ctf_event_class_get_context_type() for the
393 parent class of \p event.
394 @postrefcountsame{event}
395 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
396 count of \p context is incremented.
398 @sa bt_ctf_event_get_context(): Returns the context field of a given event.
400 extern int bt_ctf_event_set_event_context(struct bt_ctf_event
*event
,
401 struct bt_ctf_field
*context
);
404 @brief Returns the payload field of the CTF IR event \p event.
406 @param[in] event Event of which to get the payload field.
407 @returns Payload field of \p event, or \c NULL if the payload
408 field is not set or on error.
411 @postrefcountsame{event}
412 @postsuccessrefcountretinc
414 @sa bt_ctf_event_set_payload_field(): Sets the payload field of a given
417 extern struct bt_ctf_field
*bt_ctf_event_get_payload_field(
418 struct bt_ctf_event
*event
);
421 @brief Sets the payload field of the CTF IR event \p event to \p payload,
422 or unsets the current event payload field from \p event.
424 If \p payload is not \c NULL, the field type of \p payload, as returned by
425 bt_ctf_field_get_type(), \em must be equivalent to the field type returned by
426 bt_ctf_event_class_get_payload_type() for the parent class of \p event.
428 @param[in] event Event of which to set the payload field.
429 @param[in] payload Event payload field.
430 @returns 0 on success, or a negative value on error.
434 @pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
435 the field typereturned by bt_ctf_event_class_get_payload_type() for the
436 parent class of \p event.
437 @postrefcountsame{event}
438 @post <strong>On success, if \p payload is not \c NULL</strong>, the reference
439 count of \p payload is incremented.
441 @sa bt_ctf_event_get_payload(): Returns the payload field of a given event.
443 extern int bt_ctf_event_set_payload_field(struct bt_ctf_event
*event
,
444 struct bt_ctf_field
*payload
);
446 /** @cond DOCUMENT */
451 * bt_ctf_event_get_payload: get an event's field.
453 * Returns the field matching "name". bt_put() must be called on the
456 * @param event Event instance.
457 * @param name Event field name, see notes.
459 * Returns a field instance on success, NULL on error.
461 * Note: Passing a name will cause the function to perform a look-up by
462 * name assuming the event's payload is a structure. This will return
463 * the raw payload instance if name is NULL.
465 extern struct bt_ctf_field
*bt_ctf_event_get_payload(struct bt_ctf_event
*event
,
471 * bt_ctf_event_get_payload_by_index: Get event's field by index.
473 * Returns the field associated with the provided index. bt_put()
474 * must be called on the returned value. The indexes to be provided are
475 * the same as can be retrieved from the event class.
477 * @param event Event.
478 * @param index Index of field.
480 * Returns the event's field, NULL on error.
482 * Note: Will return an error if the payload's type is not a structure.
484 extern struct bt_ctf_field
*bt_ctf_event_get_payload_by_index(
485 struct bt_ctf_event
*event
, int index
);
490 * bt_ctf_event_set_payload: set an event's field.
492 * Set a manually allocated field as an event's payload. The event will share
493 * the field's ownership by using its reference count.
494 * bt_put() must be called on the returned value.
496 * @param event Event instance.
497 * @param name Event field name, see notes.
498 * @param value Instance of a field whose type corresponds to the event's field.
500 * Returns 0 on success, a negative value on error.
502 * Note: The function will return an error if a name is provided and the payload
503 * type is not a structure. If name is NULL, the payload field will be set
504 * directly and must match the event class' payload's type.
506 extern int bt_ctf_event_set_payload(struct bt_ctf_event
*event
,
508 struct bt_ctf_field
*value
);
515 @name Clock value functions
520 @brief Returns the value, as of the CTF IR event \p event, of the
521 clock described by the
522 \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
524 @param[in] event Event of which to get the value of the clock
525 described by \p clock_class.
526 @param[in] clock_class Class of the clock of which to get the value.
527 @returns Value of the clock described by \p clock_class
531 @prenotnull{clock_class}
532 @postrefcountsame{event}
533 @postrefcountsame{clock_class}
534 @postsuccessrefcountretinc
536 @sa bt_ctf_event_set_clock_value(): Sets the clock value of a given event.
538 extern struct bt_ctf_clock_value
*bt_ctf_event_get_clock_value(
539 struct bt_ctf_event
*event
, struct bt_ctf_clock_class
*clock_class
);
542 @brief Sets the value, as of the CTF IR event \p event, of the
543 clock described by its \link ctfirclockclass CTF IR
546 @param[in] event Event of which to set the value of the clock
547 described by the clock class of \p clock_value.
548 @param[in] clock_value Value of the clock described by its clock class
550 @returns 0 on success, or a negative value on error.
553 @prenotnull{clock_value}
555 @postrefcountsame{event}
557 @sa bt_ctf_event_get_clock_value(): Returns the clock value of
560 extern int bt_ctf_event_set_clock_value(
561 struct bt_ctf_event
*event
,
562 struct bt_ctf_clock_value
*clock_value
);
572 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.043087 seconds and 4 git commands to generate.