c571ca0bff23d01164b8bad9255e966273c8d2a6
2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_EVENT_H
8 #define BABELTRACE2_TRACE_IR_EVENT_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-ev Event
29 An <strong><em>event</em></strong> represents a trace event record.
31 An event is an instance of an \bt_ev_cls:
33 @image html trace-structure.png
35 In the illustration above, notice that:
37 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
38 some of which are \bt_p_ev_msg.
39 - An event message contains an \bt_ev.
40 - An event is an instance of an event class.
41 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
42 instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
43 which an event class contains.
45 Borrow the class of an event with bt_event_borrow_class() and
46 bt_event_borrow_class_const().
48 An event is a \ref api-tir "trace IR" data object.
50 You cannot directly create an event: there's no
51 <code>bt_event_create()</code> function. The \bt_name library
52 creates an event within an \bt_ev_msg from an \bt_ev_cls.
53 Therefore, to fill the fields of an event, you must first
54 borrow the event from an event message with
55 bt_message_event_borrow_event().
57 An event is a \ref api-fund-unique-object "unique object": it belongs to
60 Some library functions \ref api-fund-freezing "freeze" events on
61 success. The documentation of those functions indicate this
64 The type of an event is #bt_event.
66 An event conceptually belongs to a \bt_stream. Borrow the stream of an
67 event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
69 If the event's stream's class
70 \ref api-tir-stream-cls-prop-supports-pkt "supports packets",
71 the event also belongs to a \bt_pkt. In that case, borrow the packet of
72 an event with bt_event_borrow_packet() and
73 bt_event_borrow_packet_const().
75 Because a stream or a packet could contain millions of events, there are
76 no actual links from a stream or from a packet to its events.
80 An event has the following properties:
83 <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
85 Event's payload \bt_field.
87 The payload of an event contains its main trace data.
89 The \ref api-tir-fc "class" of an event's payload field is set
90 at the event's \ref api-tir-ev-cls "class" level. See
91 bt_event_class_set_payload_field_class(),
92 bt_event_class_borrow_payload_field_class(), and
93 bt_event_class_borrow_payload_field_class_const().
95 Use bt_event_borrow_payload_field() and
96 bt_event_borrow_payload_field_const().
99 <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
101 Event's specific context \bt_field.
103 The specific context of an event contains
104 any contextual data of which the layout is specific to the
105 event's \ref api-tir-ev-cls "class" and which does not belong to the
108 The \ref api-tir-fc "class" of an event's specific context field is
109 set at the event's \ref api-tir-ev-cls "class" level. See
110 bt_event_class_set_specific_context_field_class()
111 bt_event_class_borrow_specific_context_field_class(),
112 and bt_event_class_borrow_specific_context_field_class_const()
114 Use bt_event_borrow_specific_context_field() and
115 bt_event_borrow_specific_context_field_const().
118 <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
120 Event's common context \bt_field.
122 The common context of an event contains contextual data of which the
123 layout is common to all the \bt_p_ev_cls of the
124 event's stream's \ref api-tir-stream-cls "class".
126 The \ref api-tir-fc "class" of an event's common context field is set
127 at the event's \bt_stream_cls level. See
128 bt_stream_class_set_event_common_context_field_class()
129 bt_stream_class_borrow_event_common_context_field_class(),
130 and bt_stream_class_borrow_event_common_context_field_class_const().
132 Use bt_event_borrow_common_context_field() and
133 bt_event_borrow_common_context_field_const().
144 @typedef struct bt_event bt_event;
159 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
162 Event of which to borrow the class.
165 \em Borrowed reference of the class of \bt_p{event}.
167 @bt_pre_not_null{event}
169 @sa bt_event_borrow_class_const() —
170 \c const version of this function.
172 extern bt_event_class
*bt_event_borrow_class(bt_event
*event
);
176 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
179 See bt_event_borrow_class().
181 extern const bt_event_class
*bt_event_borrow_class_const(
182 const bt_event
*event
);
193 Borrows the \bt_stream conceptually containing the event
197 Event of which to borrow the stream conceptually containing it.
200 \em Borrowed reference of the stream conceptually containing
203 @bt_pre_not_null{event}
205 @sa bt_event_borrow_stream_const() —
206 \c const version of this function.
208 extern bt_stream
*bt_event_borrow_stream(bt_event
*event
);
212 Borrows the \bt_stream conceptually containing the event
213 \bt_p{event} (\c const version).
215 See bt_event_borrow_stream().
217 extern const bt_stream
*bt_event_borrow_stream_const(
218 const bt_event
*event
);
229 Borrows the \bt_pkt conceptually containing the event
233 Only call this function if bt_stream_class_supports_packets()
234 returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
237 Event of which to borrow the packet conceptually containing it.
240 \em Borrowed reference of the packet conceptually containing
243 @bt_pre_not_null{event}
245 @sa bt_event_borrow_packet_const() —
246 \c const version of this function.
248 extern bt_packet
*bt_event_borrow_packet(bt_event
*event
);
252 Borrows the \bt_pkt conceptually containing the event
253 \bt_p{event} (\c const version).
255 See bt_event_borrow_packet().
257 extern const bt_packet
*bt_event_borrow_packet_const(
258 const bt_event
*event
);
269 Borrows the payload \bt_field of the event \bt_p{event}.
271 See the \ref api-tir-ev-prop-payload "payload field" property.
274 Event of which to borrow the payload field.
277 \em Borrowed reference of the payload field of \bt_p{event},
280 @bt_pre_not_null{event}
282 @sa bt_event_borrow_payload_field_const() —
283 \c const version of this function.
285 extern bt_field
*bt_event_borrow_payload_field(bt_event
*event
);
289 Borrows the payload \bt_field of the event \bt_p{event}
292 See bt_event_borrow_payload_field().
294 extern const bt_field
*bt_event_borrow_payload_field_const(
295 const bt_event
*event
);
299 Borrows the specific context \bt_field of the event \bt_p{event}.
301 See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
304 Event of which to borrow the specific context field.
307 \em Borrowed reference of the specific context field of
308 \bt_p{event}, or \c NULL if none.
310 @bt_pre_not_null{event}
312 @sa bt_event_borrow_specific_context_field_const() —
313 \c const version of this function.
316 bt_event_borrow_specific_context_field(bt_event
*event
);
320 Borrows the specific context \bt_field of the event \bt_p{event}
323 See bt_event_borrow_specific_context_field().
325 extern const bt_field
*bt_event_borrow_specific_context_field_const(
326 const bt_event
*event
);
330 Borrows the common context \bt_field of the event \bt_p{event}.
332 See the \ref api-tir-ev-prop-common-ctx "common context field" property.
335 Event of which to borrow the common context field.
338 \em Borrowed reference of the common context field of
339 \bt_p{event}, or \c NULL if none.
341 @bt_pre_not_null{event}
343 @sa bt_event_borrow_specific_context_field_const() —
344 \c const version of this function.
347 bt_event_borrow_common_context_field(bt_event
*event
);
351 Borrows the common context \bt_field of the event \bt_p{event}
354 See bt_event_borrow_common_context_field().
356 extern const bt_field
*bt_event_borrow_common_context_field_const(
357 const bt_event
*event
);
367 #endif /* BABELTRACE2_TRACE_IR_EVENT_H */
This page took 0.036614 seconds and 3 git commands to generate.