lib: metadata: transform fast path precond. checks to BT_ASSERT_PRE()
[babeltrace.git] / include / babeltrace / ctf-ir / event.h
1 #ifndef BABELTRACE_CTF_IR_EVENT_H
2 #define BABELTRACE_CTF_IR_EVENT_H
3
4 /*
5 * BabelTrace - CTF IR: Event
6 *
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
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:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
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
27 * SOFTWARE.
28 *
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
31 */
32
33 #include <stdint.h>
34 #include <stddef.h>
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40 struct bt_value;
41 struct bt_clock_class;
42
43 /**
44 @defgroup ctfirevent CTF IR event
45 @ingroup ctfir
46 @brief CTF IR event.
47
48 @code
49 #include <babeltrace/ctf-ir/event.h>
50 @endcode
51
52 A CTF IR <strong><em>event</em></strong> is a container of event
53 fields:
54
55 - <strong>Stream event header</strong> field, described by the
56 <em>stream event header field type</em> of a
57 \link ctfirstreamclass CTF IR stream class\endlink.
58 - <strong>Stream event context</strong> field, described by the
59 <em>stream event context field type</em> of a stream class.
60 - <strong>Event context</strong> field, described by the
61 <em>event context field type</em> of a
62 \link ctfireventclass CTF IR event class\endlink.
63 - <strong>Event payload</strong>, described by the
64 <em>event payload field type</em> of an event class.
65
66 As a reminder, here's the structure of a CTF packet:
67
68 @imgpacketstructure
69
70 You can create a CTF IR event \em from a
71 \link ctfireventclass CTF IR event class\endlink with
72 bt_event_create(). The event class you use to create an event
73 object becomes its parent.
74
75 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
76 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
77 which is the parent of its event class) was created by a
78 \link ctfwriter CTF writer\endlink object, then the only possible
79 action you can do with this event object is to append it to a
80 \link ctfirstream CTF IR stream\endlink with
81 bt_stream_append_event(). Otherwise, you can create an event
82 notification with bt_notification_event_create(). The event you pass
83 to this function \em must have an attached packet object first.
84
85 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
86 event object with bt_event_set_packet().
87
88 A CTF IR event has a mapping of
89 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
90 an instance of a specific
91 \link ctfirclockclass CTF IR clock class\endlink when the event is
92 emitted. You can set an event object's clock value with
93 bt_event_set_clock_value().
94
95 As with any Babeltrace object, CTF IR event objects have
96 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
97 counts</a>. See \ref refs to learn more about the reference counting
98 management of Babeltrace objects.
99
100 bt_notification_event_create() \em freezes its event parameter on
101 success. You cannot modify a frozen event object: it is considered
102 immutable, except for \link refs reference counting\endlink.
103
104 @sa ctfireventclass
105 @sa ctfirpacket
106
107 @file
108 @brief CTF IR event type and functions.
109 @sa ctfirevent
110
111 @addtogroup ctfirevent
112 @{
113 */
114
115 /**
116 @struct bt_event
117 @brief A CTF IR event.
118 @sa ctfirevent
119 */
120 struct bt_event;
121 struct bt_clock;
122 struct bt_clock_value;
123 struct bt_event_class;
124 struct bt_field;
125 struct bt_field_type;
126 struct bt_stream_class;
127 struct bt_packet;
128
129 /**
130 @name Creation and parent access functions
131 @{
132 */
133
134 /**
135 @brief Creates a default CTF IR event from the CTF IR event class
136 \p event_class.
137
138 \p event_class \em must have a parent
139 \link ctfirstreamclass CTF IR stream class\endlink.
140
141 On success, the four fields of the created event object are not set. You
142 can set them with bt_event_set_header(),
143 bt_event_set_stream_event_context(),
144 bt_event_set_event_context(), and bt_event_set_event_payload().
145
146 This function tries to resolve the needed
147 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
148 types that are found anywhere in the context or payload field
149 types of \p event_class and in the root field types of the
150 parent stream class of \p event_class. If any automatic resolving fails,
151 this function fails. This means that, if any dynamic field type need
152 a field type which should be found in the trace packet header root
153 field type, and if the parent stream class of \p event_class was not
154 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
155 with bt_trace_add_stream_class(), then this function fails.
156
157 @param[in] event_class CTF IR event class to use to create the
158 CTF IR event.
159 @returns Created event object, or \c NULL on error.
160
161 @prenotnull{event_class}
162 @pre \p event_class has a parent stream class.
163 @postsuccessrefcountret1
164 */
165 extern struct bt_event *bt_event_create(
166 struct bt_event_class *event_class);
167
168 /**
169 @brief Returns the parent CTF IR event class of the CTF IR event
170 \p event.
171
172 This function returns a reference to the event class which was used to
173 create the event object in the first place with bt_event_create().
174
175 @param[in] event Event of which to get the parent event class.
176 @returns Parent event class of \p event,
177 or \c NULL on error.
178
179 @prenotnull{event}
180 @postrefcountsame{event}
181 @postsuccessrefcountretinc
182 */
183 extern struct bt_event_class *bt_event_get_class(
184 struct bt_event *event);
185
186 /**
187 @brief Returns the CTF IR packet associated to the CTF IR event
188 \p event.
189
190 This function returns a reference to the event class which was set to
191 \p event in the first place with bt_event_set_packet().
192
193 @param[in] event Event of which to get the associated packet.
194 @returns Packet associated to \p event,
195 or \c NULL if no packet is associated to
196 \p event or on error.
197
198 @prenotnull{event}
199 @postrefcountsame{event}
200 @postsuccessrefcountretinc
201
202 @sa bt_event_set_packet(): Associates a given event to a given
203 packet.
204 */
205 extern struct bt_packet *bt_event_get_packet(
206 struct bt_event *event);
207
208 /**
209 @brief Associates the CTF IR event \p event to the CTF IR packet
210 \p packet.
211
212 The \link ctfirstreamclass CTF IR stream class\endlink of the
213 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
214 be the same as the parent stream class of the
215 \link ctfireventclass CTF IR event class\endlink returned
216 by bt_event_get_class() for \p event.
217
218 You \em must call this function to create an event-packet association
219 before you call bt_notification_event_create() with \p event.
220
221 On success, this function also sets the parent stream object of
222 \p event to the parent stream of \p packet.
223
224 @param[in] event Event to which to associate \p packet.
225 @param[in] packet Packet to associate to \p event.
226 @returns 0 on success, or a negative value on error.
227
228 @prenotnull{event}
229 @prenotnull{packet}
230 @prehot{event}
231 @pre The parent stream class of \p packet is the same as the parent
232 stream class of \p event.
233 @postsuccessrefcountretinc
234
235 @sa bt_event_get_packet(): Returns the associated packet of a
236 given event object.
237 */
238 extern int bt_event_set_packet(struct bt_event *event,
239 struct bt_packet *packet);
240
241 /**
242 @brief Returns the parent CTF IR stream associated to the CTF IR event
243 \p event.
244
245 @param[in] event Event of which to get the parent stream.
246 @returns Parent stream of \p event, or \c NULL on error.
247
248 @prenotnull{event}
249 @postrefcountsame{event}
250 @postsuccessrefcountretinc
251 */
252 extern struct bt_stream *bt_event_get_stream(
253 struct bt_event *event);
254
255 /** @} */
256
257 /**
258 @name Contained fields functions
259 @{
260 */
261
262 /**
263 @brief Returns the stream event header field of the CTF IR event
264 \p event.
265
266 @param[in] event Event of which to get the stream event header
267 field.
268 @returns Stream event header field of \p event,
269 or \c NULL if the stream event header
270 field is not set or on error.
271
272 @prenotnull{event}
273 @postrefcountsame{event}
274 @postsuccessrefcountretinc
275
276 @sa bt_event_get_header(): Sets the stream event header
277 field of a given event.
278 */
279 extern struct bt_field *bt_event_get_header(
280 struct bt_event *event);
281
282 /**
283 @brief Sets the stream event header field of the CTF IR event
284 \p event to \p header, or unsets the current stream event header field
285 from \p event.
286
287 If \p header is not \c NULL, the field type of \p header, as returned by
288 bt_field_get_type(), \em must be equivalent to the field type returned by
289 bt_stream_class_get_event_header_type() for the parent stream class
290 of \p event.
291
292 @param[in] event Event of which to set the stream event header
293 field.
294 @param[in] header Stream event header field.
295 @returns 0 on success, or a negative value on error.
296
297 @prenotnull{event}
298 @prehot{event}
299 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
300 the field type returned by bt_stream_class_get_event_header_type()
301 for the parent stream class of \p event.
302 @postrefcountsame{event}
303 @post <strong>On success, if \p header is not \c NULL</strong>,
304 the reference count of \p header is incremented.
305
306 @sa bt_event_get_header(): Returns the stream event header field
307 of a given event.
308 */
309 extern int bt_event_set_header(struct bt_event *event,
310 struct bt_field *header);
311
312 /**
313 @brief Returns the stream event context field of the CTF IR event
314 \p event.
315
316 @param[in] event Event of which to get the stream event context
317 field.
318 @returns Stream event context field of \p event,
319 or \c NULL if the stream event context
320 field is not set or on error.
321
322 @prenotnull{event}
323 @postrefcountsame{event}
324 @postsuccessrefcountretinc
325
326 @sa bt_event_set_stream_event_context(): Sets the stream event context
327 field of a given event.
328 */
329 extern struct bt_field *bt_event_get_stream_event_context(
330 struct bt_event *event);
331
332 /**
333 @brief Sets the stream event context field of the CTF IR event
334 \p event to \p context, or unsets the current stream event context field
335 from \p event.
336
337 If \p context is not \c NULL, the field type of \p context, as returned by
338 bt_field_get_type(), \em must be equivalent to the field type returned by
339 bt_stream_class_get_event_context_type() for the parent stream class
340 of \p event.
341
342 @param[in] event Event of which to set the stream event context field.
343 @param[in] context Stream event context field.
344 @returns 0 on success, or a negative value on error.
345
346 @prenotnull{event}
347 @prehot{event}
348 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
349 the field type returned by bt_stream_class_get_event_context_type()
350 for the parent stream class of \p event.
351 @postrefcountsame{event}
352 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
353 count of \p context is incremented.
354
355 @sa bt_event_get_stream_event_context(): Returns the stream event context
356 field of a given event.
357 */
358 extern int bt_event_set_stream_event_context(struct bt_event *event,
359 struct bt_field *context);
360
361 /**
362 @brief Returns the event context field of the CTF IR event \p event.
363
364 @param[in] event Event of which to get the context field.
365 @returns Event context field of \p event, or \c NULL if the
366 event context field is not set or on error.
367
368 @prenotnull{event}
369 @postrefcountsame{event}
370 @postsuccessrefcountretinc
371
372 @sa bt_event_set_event_context(): Sets the event context field of a given
373 event.
374 */
375 extern struct bt_field *bt_event_get_event_context(
376 struct bt_event *event);
377
378 /**
379 @brief Sets the event context field of the CTF IR event \p event to \p context,
380 or unsets the current event context field from \p event.
381
382 If \p context is not \c NULL, the field type of \p context, as returned by
383 bt_field_get_type(), \em must be equivalent to the field type returned by
384 bt_event_class_get_context_type() for the parent class of \p event.
385
386 @param[in] event Event of which to set the context field.
387 @param[in] context Event context field.
388 @returns 0 on success, or a negative value on error.
389
390 @prenotnull{event}
391 @prehot{event}
392 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
393 the field type returned by bt_event_class_get_context_type() for the
394 parent class of \p event.
395 @postrefcountsame{event}
396 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
397 count of \p context is incremented.
398
399 @sa bt_event_get_context(): Returns the context field of a given event.
400 */
401 extern int bt_event_set_event_context(struct bt_event *event,
402 struct bt_field *context);
403
404 /**
405 @brief Returns the payload field of the CTF IR event \p event.
406
407 @param[in] event Event of which to get the payload field.
408 @returns Payload field of \p event, or \c NULL if the payload
409 field is not set or on error.
410
411 @prenotnull{event}
412 @postrefcountsame{event}
413 @postsuccessrefcountretinc
414
415 @sa bt_event_set_event_payload(): Sets the payload field of a given
416 event.
417 */
418 extern struct bt_field *bt_event_get_event_payload(
419 struct bt_event *event);
420
421 /**
422 @brief Sets the payload field of the CTF IR event \p event to \p payload,
423 or unsets the current event payload field from \p event.
424
425 If \p payload is not \c NULL, the field type of \p payload, as returned by
426 bt_field_get_type(), \em must be equivalent to the field type returned by
427 bt_event_class_get_payload_type() for the parent class of \p event.
428
429 @param[in] event Event of which to set the payload field.
430 @param[in] payload Event payload field.
431 @returns 0 on success, or a negative value on error.
432
433 @prenotnull{event}
434 @prehot{event}
435 @pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
436 the field typereturned by bt_event_class_get_payload_type() for the
437 parent class of \p event.
438 @postrefcountsame{event}
439 @post <strong>On success, if \p payload is not \c NULL</strong>, the reference
440 count of \p payload is incremented.
441
442 @sa bt_event_get_payload(): Returns the payload field of a given event.
443 */
444 extern int bt_event_set_event_payload(struct bt_event *event,
445 struct bt_field *payload);
446
447 /** @cond DOCUMENT */
448
449 /*
450 * TODO: Doxygenize.
451 *
452 * bt_event_get_payload: get an event's field.
453 *
454 * Returns the field matching "name". bt_put() must be called on the
455 * returned value.
456 *
457 * @param event Event instance.
458 * @param name Event field name, see notes.
459 *
460 * Returns a field instance on success, NULL on error.
461 *
462 * Note: Passing a name will cause the function to perform a look-up by
463 * name assuming the event's payload is a structure. This will return
464 * the raw payload instance if name is NULL.
465 */
466 extern struct bt_field *bt_event_get_payload(struct bt_event *event,
467 const char *name);
468
469 /*
470 * TODO: Doxygenize.
471 *
472 * bt_event_get_payload_by_index: Get event's field by index.
473 *
474 * Returns the field associated with the provided index. bt_put()
475 * must be called on the returned value. The indexes to be provided are
476 * the same as can be retrieved from the event class.
477 *
478 * @param event Event.
479 * @param index Index of field.
480 *
481 * Returns the event's field, NULL on error.
482 *
483 * Note: Will return an error if the payload's type is not a structure.
484 */
485 extern struct bt_field *bt_event_get_payload_by_index(
486 struct bt_event *event, uint64_t index);
487
488 /*
489 * TODO: Doxygenize.
490 *
491 * bt_event_set_payload: set an event's field.
492 *
493 * Set a manually allocated field as an event's payload. The event will share
494 * the field's ownership by using its reference count.
495 * bt_put() must be called on the returned value.
496 *
497 * @param event Event instance.
498 * @param name Event field name, see notes.
499 * @param value Instance of a field whose type corresponds to the event's field.
500 *
501 * Returns 0 on success, a negative value on error.
502 *
503 * Note: The function will return an error if a name is provided and the payload
504 * type is not a structure. If name is NULL, the payload field will be set
505 * directly and must match the event class' payload's type.
506 */
507 extern int bt_event_set_payload(struct bt_event *event,
508 const char *name,
509 struct bt_field *value);
510
511 /** @endcond */
512
513 /** @} */
514
515 /**
516 @name Clock value functions
517 @{
518 */
519
520 /**
521 @brief Returns the value, as of the CTF IR event \p event, of the
522 clock described by the
523 \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
524
525 @param[in] event Event of which to get the value of the clock
526 described by \p clock_class.
527 @param[in] clock_class Class of the clock of which to get the value.
528 @returns Value of the clock described by \p clock_class
529 as of \p event.
530
531 @prenotnull{event}
532 @prenotnull{clock_class}
533 @postrefcountsame{event}
534 @postrefcountsame{clock_class}
535 @postsuccessrefcountretinc
536
537 @sa bt_event_set_clock_value(): Sets the clock value of a given event.
538 */
539 extern struct bt_clock_value *bt_event_get_clock_value(
540 struct bt_event *event,
541 struct bt_clock_class *clock_class);
542
543 /**
544 @brief Sets the value, as of the CTF IR event \p event, of the
545 clock described by its \link ctfirclockclass CTF IR
546 clock class\endlink.
547
548 @param[in] event Event of which to set the value of the clock
549 described by the clock class of \p clock_value.
550 @param[in] clock_value Value of the clock described by its clock class
551 as of \p event.
552 @returns 0 on success, or a negative value on error.
553
554 @prenotnull{event}
555 @prenotnull{clock_value}
556 @prehot{event}
557 @postrefcountsame{event}
558
559 @sa bt_event_get_clock_value(): Returns the clock value of
560 a given event.
561 */
562 extern int bt_event_set_clock_value(
563 struct bt_event *event,
564 struct bt_clock_value *clock_value);
565
566 /** @} */
567
568 /** @} */
569
570 /* Pre-2.0 CTF writer compatibility */
571 #define bt_ctf_event bt_event
572 #define bt_ctf_event_create bt_event_create
573 #define bt_ctf_event_get_payload bt_event_get_payload
574 #define bt_ctf_event_set_payload bt_event_set_payload
575
576 #ifdef __cplusplus
577 }
578 #endif
579
580 #endif /* BABELTRACE_CTF_IR_EVENT_H */
This page took 0.04273 seconds and 4 git commands to generate.