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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
21 @defgroup api-tir-ev Event
27 An <strong><em>event</em></strong> represents a trace event record.
29 An event is an instance of an \bt_ev_cls:
31 @image html trace-structure.png
33 In the illustration above, notice that:
35 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
36 some of which are \bt_p_ev_msg.
37 - An event message contains an \bt_ev.
38 - An event is an instance of an event class.
39 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
40 instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
41 which an event class contains.
43 Borrow the class of an event with bt_event_borrow_class() and
44 bt_event_borrow_class_const().
46 An event is a \ref api-tir "trace IR" data object.
48 You cannot directly create an event: there's no
49 <code>bt_event_create()</code> function. The \bt_name library
50 creates an event within an \bt_ev_msg from an \bt_ev_cls.
51 Therefore, to fill the fields of an event, you must first
52 borrow the event from an event message with
53 bt_message_event_borrow_event().
55 An event is a \ref api-fund-unique-object "unique object": it belongs to
58 Some library functions \ref api-fund-freezing "freeze" events on
59 success. The documentation of those functions indicate this
62 The type of an event is #bt_event.
64 An event conceptually belongs to a \bt_stream. Borrow the stream of an
65 event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
67 If the event's stream's class
68 \ref api-tir-stream-cls-prop-supports-pkt "supports packets",
69 the event also belongs to a \bt_pkt. In that case, borrow the packet of
70 an event with bt_event_borrow_packet() and
71 bt_event_borrow_packet_const().
73 Because a stream or a packet could contain millions of events, there are
74 no actual links from a stream or from a packet to its events.
78 An event has the following properties:
81 <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
83 Event's payload \bt_field.
85 The payload of an event contains its main trace data.
87 The \ref api-tir-fc "class" of an event's payload field is set
88 at the event's \ref api-tir-ev-cls "class" level. See
89 bt_event_class_set_payload_field_class(),
90 bt_event_class_borrow_payload_field_class(), and
91 bt_event_class_borrow_payload_field_class_const().
93 Use bt_event_borrow_payload_field() and
94 bt_event_borrow_payload_field_const().
97 <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
99 Event's specific context \bt_field.
101 The specific context of an event contains
102 any contextual data of which the layout is specific to the
103 event's \ref api-tir-ev-cls "class" and which does not belong to the
106 The \ref api-tir-fc "class" of an event's specific context field is
107 set at the event's \ref api-tir-ev-cls "class" level. See
108 bt_event_class_set_specific_context_field_class()
109 bt_event_class_borrow_specific_context_field_class(),
110 and bt_event_class_borrow_specific_context_field_class_const()
112 Use bt_event_borrow_specific_context_field() and
113 bt_event_borrow_specific_context_field_const().
116 <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
118 Event's common context \bt_field.
120 The common context of an event contains contextual data of which the
121 layout is common to all the \bt_p_ev_cls of the
122 event's stream's \ref api-tir-stream-cls "class".
124 The \ref api-tir-fc "class" of an event's common context field is set
125 at the event's \bt_stream_cls level. See
126 bt_stream_class_set_event_common_context_field_class()
127 bt_stream_class_borrow_event_common_context_field_class(),
128 and bt_stream_class_borrow_event_common_context_field_class_const().
130 Use bt_event_borrow_common_context_field() and
131 bt_event_borrow_common_context_field_const().
142 @typedef struct bt_event bt_event;
157 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
160 Event of which to borrow the class.
163 \em Borrowed reference of the class of \bt_p{event}.
165 @bt_pre_not_null{event}
167 @sa bt_event_borrow_class_const() —
168 \c const version of this function.
170 extern bt_event_class
*bt_event_borrow_class(bt_event
*event
);
174 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
177 See bt_event_borrow_class().
179 extern const bt_event_class
*bt_event_borrow_class_const(
180 const bt_event
*event
);
191 Borrows the \bt_stream conceptually containing the event
195 Event of which to borrow the stream conceptually containing it.
198 \em Borrowed reference of the stream conceptually containing
201 @bt_pre_not_null{event}
203 @sa bt_event_borrow_stream_const() —
204 \c const version of this function.
206 extern bt_stream
*bt_event_borrow_stream(bt_event
*event
);
210 Borrows the \bt_stream conceptually containing the event
211 \bt_p{event} (\c const version).
213 See bt_event_borrow_stream().
215 extern const bt_stream
*bt_event_borrow_stream_const(
216 const bt_event
*event
);
227 Borrows the \bt_pkt conceptually containing the event
231 Only call this function if bt_stream_class_supports_packets()
232 returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
235 Event of which to borrow the packet conceptually containing it.
238 \em Borrowed reference of the packet conceptually containing
241 @bt_pre_not_null{event}
243 @sa bt_event_borrow_packet_const() —
244 \c const version of this function.
246 extern bt_packet
*bt_event_borrow_packet(bt_event
*event
);
250 Borrows the \bt_pkt conceptually containing the event
251 \bt_p{event} (\c const version).
253 See bt_event_borrow_packet().
255 extern const bt_packet
*bt_event_borrow_packet_const(
256 const bt_event
*event
);
267 Borrows the payload \bt_field of the event \bt_p{event}.
269 See the \ref api-tir-ev-prop-payload "payload field" property.
272 Event of which to borrow the payload field.
275 \em Borrowed reference of the payload field of \bt_p{event},
278 @bt_pre_not_null{event}
280 @sa bt_event_borrow_payload_field_const() —
281 \c const version of this function.
283 extern bt_field
*bt_event_borrow_payload_field(bt_event
*event
);
287 Borrows the payload \bt_field of the event \bt_p{event}
290 See bt_event_borrow_payload_field().
292 extern const bt_field
*bt_event_borrow_payload_field_const(
293 const bt_event
*event
);
297 Borrows the specific context \bt_field of the event \bt_p{event}.
299 See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
302 Event of which to borrow the specific context field.
305 \em Borrowed reference of the specific context field of
306 \bt_p{event}, or \c NULL if none.
308 @bt_pre_not_null{event}
310 @sa bt_event_borrow_specific_context_field_const() —
311 \c const version of this function.
314 bt_event_borrow_specific_context_field(bt_event
*event
);
318 Borrows the specific context \bt_field of the event \bt_p{event}
321 See bt_event_borrow_specific_context_field().
323 extern const bt_field
*bt_event_borrow_specific_context_field_const(
324 const bt_event
*event
);
328 Borrows the common context \bt_field of the event \bt_p{event}.
330 See the \ref api-tir-ev-prop-common-ctx "common context field" property.
333 Event of which to borrow the common context field.
336 \em Borrowed reference of the common context field of
337 \bt_p{event}, or \c NULL if none.
339 @bt_pre_not_null{event}
341 @sa bt_event_borrow_specific_context_field_const() —
342 \c const version of this function.
345 bt_event_borrow_common_context_field(bt_event
*event
);
349 Borrows the common context \bt_field of the event \bt_p{event}
352 See bt_event_borrow_common_context_field().
354 extern const bt_field
*bt_event_borrow_common_context_field_const(
355 const bt_event
*event
);
365 #endif /* BABELTRACE2_TRACE_IR_EVENT_H */
This page took 0.036763 seconds and 4 git commands to generate.