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>
42 @defgroup ctfirevent CTF IR event
46 A CTF IR <strong><em>event</em></strong> is a container of event
49 - <strong>Stream event header</strong> field, described by the
50 <em>stream event header field type</em> of a
51 \link ctfirstreamclass CTF IR stream class\endlink.
52 - <strong>Stream event context</strong> field, described by the
53 <em>stream event context field type</em> of a stream class.
54 - <strong>Event context</strong> field, described by the
55 <em>event context field type</em> of a
56 \link ctfireventclass CTF IR event class\endlink.
57 - <strong>Event payload</strong>, described by the
58 <em>event payload field type</em> of an event class.
60 As a reminder, here's the structure of a CTF packet:
64 You can create a CTF IR event \em from a
65 \link ctfireventclass CTF IR event class\endlink with
66 bt_ctf_event_create(). The event class you use to create an event
67 object becomes its parent.
69 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
70 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
71 which is the parent of its event class) was created by a
72 \link ctfirwriter CTF IR writer\endlink object, then the only possible
73 action you can do with this event object is to append it to a
74 \link ctfirstream CTF IR stream\endlink with
75 bt_ctf_stream_append_event(). Otherwise, you can create an event
76 notification with bt_notification_event_create(). The event you pass
77 to this function \em must have an attached packet object first.
79 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
80 event object with bt_ctf_event_set_packet().
82 A CTF IR event has a mapping of
83 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
84 an instance of a specific
85 \link ctfirclockclass CTF IR clock class\endlink when the event is
86 emitted. You can set an event object's clock value with
87 bt_ctf_event_set_clock_value().
89 As with any Babeltrace object, CTF IR event objects have
90 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
91 counts</a>. See \ref refs to learn more about the reference counting
92 management of Babeltrace objects.
94 bt_notification_event_create() \em freezes its event parameter on
95 success. You cannot modify a frozen event object: it is considered
96 immutable, except for \link refs reference counting\endlink.
102 @brief CTF IR event type and functions.
105 @addtogroup ctfirevent
111 @brief A CTF IR event.
116 struct bt_ctf_clock_value
;
117 struct bt_ctf_event_class
;
119 struct bt_ctf_field_type
;
120 struct bt_ctf_stream_class
;
121 struct bt_ctf_packet
;
124 @name Creation and parent access functions
129 @brief Creates a default CTF IR event from the CTF IR event class
132 \p event_class \em must have a parent
133 \link ctfirstreamclass CTF IR stream class\endlink.
135 On success, the four fields of the created event object are not set. You
136 can set them with bt_ctf_event_set_header(),
137 bt_ctf_event_set_stream_event_context(),
138 bt_ctf_event_set_event_context(), and bt_ctf_event_set_payload_field().
140 @param[in] event_class CTF IR event class to use to create the
142 @returns Created event object, or \c NULL on error.
144 @prenotnull{event_class}
145 @pre \p event_class has a parent stream class.
146 @postsuccessrefcountret1
148 extern struct bt_ctf_event
*bt_ctf_event_create(
149 struct bt_ctf_event_class
*event_class
);
152 @brief Returns the parent CTF IR event class of the CTF IR event
155 This function returns a reference to the event class which was used to
156 create the event object in the first place with bt_ctf_event_create().
158 @param[in] event Event of which to get the parent event class.
159 @returns Parent event class of \p event,
163 @postsuccessrefcountretinc
165 extern struct bt_ctf_event_class
*bt_ctf_event_get_class(
166 struct bt_ctf_event
*event
);
169 @brief Returns the CTF IR packet associated to the CTF IR event
172 This function returns a reference to the event class which was set to
173 \p event in the first place with bt_ctf_event_set_packet().
175 @param[in] event Event of which to get the associated packet.
176 @returns Packet associated to \p event,
177 or \c NULL if no packet is associated to
178 \p event or on error.
181 @postsuccessrefcountretinc
183 @sa bt_ctf_event_set_packet(): Associates a given event to a given
186 extern struct bt_ctf_packet
*bt_ctf_event_get_packet(
187 struct bt_ctf_event
*event
);
190 @brief Associates the CTF IR event \p event to the CTF IR packet
193 The \link ctfirstreamclass CTF IR stream class\endlink of the
194 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
195 be the same as the parent stream class of the
196 \link ctfireventclass CTF IR event class\endlink returned
197 by bt_ctf_event_get_class() for \p event.
199 You \em must call this function to create an event-packet association
200 before you call bt_notification_event_create() with \p event.
202 On success, this function also sets the parent stream object of
203 \p event to the parent stream of \p packet.
205 @param[in] event Event to which to associate \p packet.
206 @returns 0 on success, or a negative value on error.
211 @pre The parent stream class of \p packet is the same as the parent
212 stream class of \p event.
213 @postsuccessrefcountretinc
215 @sa bt_ctf_event_get_packet(): Returns the associated packet of a
218 extern int bt_ctf_event_set_packet(struct bt_ctf_event
*event
,
219 struct bt_ctf_packet
*packet
);
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 @postsuccessrefcountretinc
231 extern struct bt_ctf_stream
*bt_ctf_event_get_stream(
232 struct bt_ctf_event
*event
);
237 @name Contained fields functions
242 @brief Returns the stream event header field of the CTF IR event
245 @param[in] event Event of which to get the stream event header
247 @returns Stream event header field of \p event,
248 or \c NULL if the stream event header
249 field is not set or on error.
252 @postsuccessrefcountretinc
254 @sa bt_ctf_event_get_header(): Sets the stream event header
255 field of a given event.
257 extern struct bt_ctf_field
*bt_ctf_event_get_header(
258 struct bt_ctf_event
*event
);
261 @brief Sets the stream event header field of the CTF IR event
262 \p event to \p header.
264 The field type of \p header, as returned by bt_ctf_field_get_type(),
265 \em must be equivalent to the field type returned by
266 bt_ctf_stream_class_get_event_header_type() for the parent stream class
269 @param[in] event Event of which to set the stream event header
271 @param[in] header Stream event header field.
272 @returns 0 on success, or a negative value on error.
277 @pre \p header has a field type equivalent to the field type returned by
278 bt_ctf_stream_class_get_event_header_type() for the parent
279 stream class of \p event.
280 @postrefcountsame{event}
281 @postsuccessrefcountinc{header}
283 @sa bt_ctf_event_get_header(): Returns the stream event header field
286 extern int bt_ctf_event_set_header(struct bt_ctf_event
*event
,
287 struct bt_ctf_field
*header
);
290 @brief Returns the stream event context field of the CTF IR event
293 @param[in] event Event of which to get the stream event context
295 @returns Stream event context field of \p event,
296 or \c NULL if the stream event context
297 field is not set or on error.
300 @postsuccessrefcountretinc
302 @sa bt_ctf_event_set_stream_event_context(): Sets the stream event
303 context field of a given event.
305 extern struct bt_ctf_field
*bt_ctf_event_get_stream_event_context(
306 struct bt_ctf_event
*event
);
309 @brief Sets the stream event context field of the CTF IR event
310 \p event to \p context.
312 The field type of \p context, as returned by bt_ctf_field_get_type(),
313 \em must be equivalent to the field type returned by
314 bt_ctf_stream_class_get_event_context_type() for the parent stream class
317 @param[in] event Event of which to set the stream event context
319 @param[in] context Stream event context field.
320 @returns 0 on success, or a negative value on error.
325 @pre \p context has a field type equivalent to the field type returned
326 by bt_ctf_stream_class_get_event_context_type() for the parent
327 stream class of \p event.
328 @postrefcountsame{event}
329 @postsuccessrefcountinc{context}
331 @sa bt_ctf_event_get_stream_event_context(): Returns the stream event
332 context field of a given event.
334 extern int bt_ctf_event_set_stream_event_context(struct bt_ctf_event
*event
,
335 struct bt_ctf_field
*context
);
338 @brief Returns the event context field of the CTF IR event
341 @param[in] event Event of which to get the event context
343 @returns Event context field of \p event, or \c NULL if
344 the event context field is not set or on error.
347 @postsuccessrefcountretinc
349 @sa bt_ctf_event_set_event_context(): Sets the event context field of a
352 extern struct bt_ctf_field
*bt_ctf_event_get_event_context(
353 struct bt_ctf_event
*event
);
356 @brief Sets the event context field of the CTF IR event
357 \p event to \p context.
359 The field type of \p context, as returned by bt_ctf_field_get_type(),
360 \em must be equivalent to the field type returned by
361 bt_ctf_event_class_get_context_type() for the parent event class
364 @param[in] event Event of which to set the event context field.
365 @param[in] context Event context field.
366 @returns 0 on success, or a negative value on error.
371 @pre \p context has a field type equivalent to the field type returned
372 by bt_ctf_event_class_get_context_type() for the parent
373 event class of \p event.
374 @postrefcountsame{event}
375 @postsuccessrefcountinc{context}
377 @sa bt_ctf_event_get_event_context(): Returns the event context field of
380 extern int bt_ctf_event_set_event_context(struct bt_ctf_event
*event
,
381 struct bt_ctf_field
*context
);
384 @brief Returns the event payload field of the CTF IR event
387 @param[in] event Event of which to get the event payload
389 @returns Event payload field of \p event, or \c NULL if
390 the event payload field is not set or on error.
393 @postsuccessrefcountretinc
395 @sa bt_ctf_event_set_payload_field(): Sets the event payload field of a
398 extern struct bt_ctf_field
*bt_ctf_event_get_payload_field(
399 struct bt_ctf_event
*event
);
402 @brief Sets the event payload field of the CTF IR event
403 \p event to \p payload.
405 The field type of \p payload, as returned by bt_ctf_field_get_type(),
406 \em must be equivalent to the field type returned by
407 bt_ctf_event_class_get_payload_type() for the parent event class
410 @param[in] event Event of which to set the event payload field.
411 @param[in] payload Event payload field.
412 @returns 0 on success, or a negative value on error.
417 @pre \p payload has a field type equivalent to the field type returned
418 by bt_ctf_event_class_get_payload_type() for the parent
419 event class of \p event.
420 @postrefcountsame{event}
421 @postsuccessrefcountinc{payload}
423 @sa bt_ctf_event_get_payload_field(): Returns the event payload field of
426 extern int bt_ctf_event_set_payload_field(struct bt_ctf_event
*event
,
427 struct bt_ctf_field
*payload
);
436 * bt_ctf_event_get_payload: get an event's field.
438 * Returns the field matching "name". bt_put() must be called on the
441 * @param event Event instance.
442 * @param name Event field name, see notes.
444 * Returns a field instance on success, NULL on error.
446 * Note: Passing a name will cause the function to perform a look-up by
447 * name assuming the event's payload is a structure. This will return
448 * the raw payload instance if name is NULL.
450 extern struct bt_ctf_field
*bt_ctf_event_get_payload(struct bt_ctf_event
*event
,
456 * bt_ctf_event_get_payload_by_index: Get event's field by index.
458 * Returns the field associated with the provided index. bt_put()
459 * must be called on the returned value. The indexes to be provided are
460 * the same as can be retrieved from the event class.
462 * @param event Event.
463 * @param index Index of field.
465 * Returns the event's field, NULL on error.
467 * Note: Will return an error if the payload's type is not a structure.
469 extern struct bt_ctf_field
*bt_ctf_event_get_payload_by_index(
470 struct bt_ctf_event
*event
, int index
);
475 * bt_ctf_event_set_payload: set an event's field.
477 * Set a manually allocated field as an event's payload. The event will share
478 * the field's ownership by using its reference count.
479 * bt_put() must be called on the returned value.
481 * @param event Event instance.
482 * @param name Event field name, see notes.
483 * @param value Instance of a field whose type corresponds to the event's field.
485 * Returns 0 on success, a negative value on error.
487 * Note: The function will return an error if a name is provided and the payload
488 * type is not a structure. If name is NULL, the payload field will be set
489 * directly and must match the event class' payload's type.
491 extern int bt_ctf_event_set_payload(struct bt_ctf_event
*event
,
493 struct bt_ctf_field
*value
);
502 @name Clock value functions
507 @brief Returns the value, as of the CTF IR event \p event, of the
508 clock described by the
509 \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
511 @param[in] event Event of which to get the value of the clock
512 described by \p clock_class.
513 @param[in] clock_class Class of the clock of which to get the value.
514 @returns Value of the clock described by \p clock_class
518 @prenotnull{clock_class}
519 @postrefcountsame{event}
520 @postrefcountsame{clock_class}
521 @postsuccessrefcountretinc
523 @sa bt_ctf_event_set_clock_value(): Sets the clock value of a given event.
525 extern struct bt_ctf_clock_value
*bt_ctf_event_get_clock_value(
526 struct bt_ctf_event
*event
, struct bt_ctf_clock
*clock_class
);
529 @brief Sets the value, as of the CTF IR event \p event, of the
530 clock described by the
531 \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
533 @param[in] event Event of which to set the value of the clock
534 described by \p clock_class.
535 @param[in] clock_class Class of the clock of which to set the value
537 @param[in] clock_value Value of the clock described by \p clock_class
539 @returns 0 on success, or a negative value on error.
542 @prenotnull{clock_class}
543 @prenotnull{clock_value}
545 @postrefcountsame{event}
546 @postrefcountsame{clock_class}
548 @sa bt_ctf_event_get_clock_value(): Returns the clock value of
551 extern int bt_ctf_event_set_clock_value(
552 struct bt_ctf_event
*event
, struct bt_ctf_clock
*clock_class
,
553 struct bt_ctf_clock_value
*clock_value
);
563 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.11082 seconds and 4 git commands to generate.