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.
125 struct bt_clock_value
;
126 struct bt_event_class
;
128 struct bt_field_type
;
129 struct bt_stream_class
;
133 @name Creation and parent access functions
138 @brief Creates a default CTF IR event from the CTF IR event class
141 \p event_class \em must have a parent
142 \link ctfirstreamclass CTF IR stream class\endlink.
144 On success, the four fields of the created event object are not set. You
145 can set them with bt_event_set_header(),
146 bt_event_set_stream_event_context(),
147 bt_event_set_context(), and bt_event_set_payload().
149 This function tries to resolve the needed
150 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
151 types that are found anywhere in the context or payload field
152 types of \p event_class and in the root field types of the
153 parent stream class of \p event_class. If any automatic resolving fails,
154 this function fails. This means that, if any dynamic field type need
155 a field type which should be found in the trace packet header root
156 field type, and if the parent stream class of \p event_class was not
157 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
158 with bt_trace_add_stream_class(), then this function fails.
160 @param[in] event_class CTF IR event class to use to create the
162 @returns Created event object, or \c NULL on error.
164 @prenotnull{event_class}
165 @pre \p event_class has a parent stream class.
166 @postsuccessrefcountret1
168 extern struct bt_event
*bt_event_create(struct bt_event_class
*event_class
);
170 extern struct bt_event_class
*bt_event_borrow_class(struct bt_event
*event
);
173 @brief Returns the parent CTF IR event class of the CTF IR event
176 This function returns a reference to the event class which was used to
177 create the event object in the first place with bt_event_create().
179 @param[in] event Event of which to get the parent event class.
180 @returns Parent event class of \p event,
184 @postrefcountsame{event}
185 @postsuccessrefcountretinc
188 struct bt_event_class
*bt_event_get_class(struct bt_event
*event
)
190 return bt_get(bt_event_borrow_class(event
));
193 extern struct bt_packet
*bt_event_borrow_packet(struct bt_event
*event
);
196 @brief Returns the CTF IR packet associated to the CTF IR event
199 This function returns a reference to the event class which was set to
200 \p event in the first place with bt_event_set_packet().
202 @param[in] event Event of which to get the associated packet.
203 @returns Packet associated to \p event,
204 or \c NULL if no packet is associated to
205 \p event or on error.
208 @postrefcountsame{event}
209 @postsuccessrefcountretinc
211 @sa bt_event_set_packet(): Associates a given event to a given
215 struct bt_packet
*bt_event_get_packet(struct bt_event
*event
)
217 return bt_get(bt_event_borrow_packet(event
));
221 @brief Associates the CTF IR event \p event to the CTF IR packet
224 The \link ctfirstreamclass CTF IR stream class\endlink of the
225 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
226 be the same as the parent stream class of the
227 \link ctfireventclass CTF IR event class\endlink returned
228 by bt_event_get_class() for \p event.
230 You \em must call this function to create an event-packet association
231 before you call bt_notification_event_create() with \p event.
233 On success, this function also sets the parent stream object of
234 \p event to the parent stream of \p packet.
236 @param[in] event Event to which to associate \p packet.
237 @param[in] packet Packet to associate to \p event.
238 @returns 0 on success, or a negative value on error.
243 @pre The parent stream class of \p packet is the same as the parent
244 stream class of \p event.
245 @postsuccessrefcountretinc
247 @sa bt_event_get_packet(): Returns the associated packet of a
250 extern int bt_event_set_packet(struct bt_event
*event
,
251 struct bt_packet
*packet
);
253 extern struct bt_stream
*bt_event_borrow_stream(struct bt_event
*event
);
256 @brief Returns the parent CTF IR stream associated to the CTF IR event
259 @param[in] event Event of which to get the parent stream.
260 @returns Parent stream of \p event, or \c NULL on error.
263 @postrefcountsame{event}
264 @postsuccessrefcountretinc
267 struct bt_stream
*bt_event_get_stream(struct bt_event
*event
)
269 return bt_get(bt_event_borrow_stream(event
));
275 @name Contained fields functions
279 extern struct bt_field
*bt_event_borrow_header(struct bt_event
*event
);
282 @brief Returns the stream event header field of the CTF IR event
285 @param[in] event Event of which to get the stream event header
287 @returns Stream event header field of \p event,
288 or \c NULL if the stream event header
289 field is not set or on error.
292 @postrefcountsame{event}
293 @postsuccessrefcountretinc
295 @sa bt_event_get_header(): Sets the stream event header
296 field of a given event.
299 struct bt_field
*bt_event_get_header(struct bt_event
*event
)
301 return bt_get(bt_event_borrow_header(event
));
305 @brief Sets the stream event header field of the CTF IR event
306 \p event to \p header, or unsets the current stream event header field
309 If \p header is not \c NULL, the field type of \p header, as returned by
310 bt_field_get_type(), \em must be equivalent to the field type returned by
311 bt_stream_class_get_event_header_type() for the parent stream class
314 @param[in] event Event of which to set the stream event header
316 @param[in] header Stream event header field.
317 @returns 0 on success, or a negative value on error.
321 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
322 the field type returned by bt_stream_class_get_event_header_type()
323 for the parent stream class of \p event.
324 @postrefcountsame{event}
325 @post <strong>On success, if \p header is not \c NULL</strong>,
326 the reference count of \p header is incremented.
328 @sa bt_event_get_header(): Returns the stream event header field
331 extern int bt_event_set_header(struct bt_event
*event
,
332 struct bt_field
*header
);
334 extern struct bt_field
*bt_event_borrow_stream_event_context(
335 struct bt_event
*event
);
338 @brief Returns the stream event context field of the CTF IR event
341 @param[in] event Event of which to get the stream event context
343 @returns Stream event context field of \p event,
344 or \c NULL if the stream event context
345 field is not set or on error.
348 @postrefcountsame{event}
349 @postsuccessrefcountretinc
351 @sa bt_event_set_stream_event_context(): Sets the stream event context
352 field of a given event.
355 struct bt_field
*bt_event_get_stream_event_context(struct bt_event
*event
)
357 return bt_get(bt_event_borrow_stream_event_context(event
));
361 @brief Sets the stream event context field of the CTF IR event
362 \p event to \p context, or unsets the current stream event context field
365 If \p context is not \c NULL, the field type of \p context, as returned by
366 bt_field_get_type(), \em must be equivalent to the field type returned by
367 bt_stream_class_get_event_context_type() for the parent stream class
370 @param[in] event Event of which to set the stream event context field.
371 @param[in] context Stream event context field.
372 @returns 0 on success, or a negative value on error.
376 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
377 the field type returned by bt_stream_class_get_event_context_type()
378 for the parent stream class of \p event.
379 @postrefcountsame{event}
380 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
381 count of \p context is incremented.
383 @sa bt_event_get_stream_event_context(): Returns the stream event context
384 field of a given event.
386 extern int bt_event_set_stream_event_context(struct bt_event
*event
,
387 struct bt_field
*context
);
389 extern struct bt_field
*bt_event_borrow_context(struct bt_event
*event
);
392 @brief Returns the event context field of the CTF IR event \p event.
394 @param[in] event Event of which to get the context field.
395 @returns Event context field of \p event, or \c NULL if the
396 event context field is not set or on error.
399 @postrefcountsame{event}
400 @postsuccessrefcountretinc
402 @sa bt_event_set_context(): Sets the event context field of a given
406 struct bt_field
*bt_event_get_context(struct bt_event
*event
)
408 return bt_get(bt_event_borrow_context(event
));
412 @brief Sets the event context field of the CTF IR event \p event to \p context,
413 or unsets the current event context field from \p event.
415 If \p context is not \c NULL, the field type of \p context, as returned by
416 bt_field_get_type(), \em must be equivalent to the field type returned by
417 bt_event_class_get_context_type() for the parent class of \p event.
419 @param[in] event Event of which to set the context field.
420 @param[in] context Event context field.
421 @returns 0 on success, or a negative value on error.
425 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
426 the field type returned by bt_event_class_get_context_type() for the
427 parent class of \p event.
428 @postrefcountsame{event}
429 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
430 count of \p context is incremented.
432 @sa bt_event_get_context(): Returns the context field of a given event.
434 extern int bt_event_set_context(struct bt_event
*event
,
435 struct bt_field
*context
);
437 extern struct bt_field
*bt_event_borrow_payload(struct bt_event
*event
);
440 @brief Returns the payload field of the CTF IR event \p event.
442 @param[in] event Event of which to get the payload field.
443 @returns Payload field of \p event, or \c NULL if the payload
444 field is not set or on error.
447 @postrefcountsame{event}
448 @postsuccessrefcountretinc
450 @sa bt_event_set_payload(): Sets the payload field of a given
454 struct bt_field
*bt_event_get_payload(struct bt_event
*event
)
456 return bt_get(bt_event_borrow_payload(event
));
460 @brief Sets the payload field of the CTF IR event \p event to \p payload,
461 or unsets the current event payload field from \p event.
463 If \p payload is not \c NULL, the field type of \p payload, as returned by
464 bt_field_get_type(), \em must be equivalent to the field type returned by
465 bt_event_class_get_payload_type() for the parent class of \p event.
467 @param[in] event Event of which to set the payload field.
468 @param[in] payload Event payload field.
469 @returns 0 on success, or a negative value on error.
473 @pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
474 the field typereturned by bt_event_class_get_payload_type() for the
475 parent class of \p event.
476 @postrefcountsame{event}
477 @post <strong>On success, if \p payload is not \c NULL</strong>, the reference
478 count of \p payload is incremented.
480 @sa bt_event_get_payload(): Returns the payload field of a given event.
482 extern int bt_event_set_payload(struct bt_event
*event
,
483 struct bt_field
*payload
);
488 @name Clock value functions
492 extern struct bt_clock_value
*bt_event_borrow_clock_value(
493 struct bt_event
*event
,
494 struct bt_clock_class
*clock_class
);
497 @brief Returns the value, as of the CTF IR event \p event, of the
498 clock described by the
499 \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
501 @param[in] event Event of which to get the value of the clock
502 described by \p clock_class.
503 @param[in] clock_class Class of the clock of which to get the value.
504 @returns Value of the clock described by \p clock_class
508 @prenotnull{clock_class}
509 @postrefcountsame{event}
510 @postrefcountsame{clock_class}
511 @postsuccessrefcountretinc
513 @sa bt_event_set_clock_value(): Sets the clock value of a given event.
516 struct bt_clock_value
*bt_event_get_clock_value(
517 struct bt_event
*event
,
518 struct bt_clock_class
*clock_class
)
520 return bt_get(bt_event_borrow_clock_value(event
, clock_class
));
524 @brief Sets the value, as of the CTF IR event \p event, of the
525 clock described by its \link ctfirclockclass CTF IR
528 @param[in] event Event of which to set the value of the clock
529 described by the clock class of \p clock_value.
530 @param[in] clock_value Value of the clock described by its clock class
532 @returns 0 on success, or a negative value on error.
535 @prenotnull{clock_value}
537 @postrefcountsame{event}
539 @sa bt_event_get_clock_value(): Returns the clock value of
542 extern int bt_event_set_clock_value(
543 struct bt_event
*event
,
544 struct bt_clock_value
*clock_value
);
554 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.042279 seconds and 4 git commands to generate.