1 #ifndef BABELTRACE2_TRACE_IR_EVENT_H
2 #define BABELTRACE2_TRACE_IR_EVENT_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
37 @defgroup api-tir-ev Event
43 An <strong><em>event</em></strong> represents a trace event record.
45 An event is an instance of an \bt_ev_cls:
47 @image html trace-structure.png
49 In the illustration above, notice that:
51 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
52 some of which are \bt_p_ev_msg.
53 - An event message contains an \bt_ev.
54 - An event is an instance of an event class.
55 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
56 instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
57 which an event class contains.
59 Borrow the class of an event with bt_event_borrow_class() and
60 bt_event_borrow_class_const().
62 An event is a \ref api-tir "trace IR" data object.
64 You cannot directly create an event: there's no
65 <code>bt_event_create()</code> function. The \bt_name library
66 creates an event within an \bt_ev_msg from an \bt_ev_cls.
67 Therefore, to fill the fields of an event, you must first
68 borrow the event from an event message with
69 bt_message_event_borrow_event().
71 An event is a \ref api-fund-unique-object "unique object": it belongs to
74 Some library functions \ref api-fund-freezing "freeze" events on
75 success. The documentation of those functions indicate this
78 The type of an event is #bt_event.
80 An event conceptually belongs to a \bt_stream. Borrow the stream of an
81 event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
83 If the event's stream's class
84 \ref api-tir-stream-cls-prop-supports-pkt "supports packets",
85 the event also belongs to a \bt_pkt. In that case, borrow the packet of
86 an event with bt_event_borrow_packet() and
87 bt_event_borrow_packet_const().
89 Because a stream or a packet could contain millions of events, there are
90 no actual links from a stream or from a packet to its events.
94 An event has the following properties:
97 <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
99 Event's payload \bt_field.
101 The payload of an event contains its main trace data.
103 The \ref api-tir-fc "class" of an event's payload field is set
104 at the event's \ref api-tir-ev-cls "class" level. See
105 bt_event_class_set_payload_field_class(),
106 bt_event_class_borrow_payload_field_class(), and
107 bt_event_class_borrow_payload_field_class_const().
109 Use bt_event_borrow_payload_field() and
110 bt_event_borrow_payload_field_const().
113 <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
115 Event's specific context \bt_field.
117 The specific context of an event contains
118 any contextual data of which the layout is specific to the
119 event's \ref api-tir-ev-cls "class" and which does not belong to the
122 The \ref api-tir-fc "class" of an event's specific context field is
123 set at the event's \ref api-tir-ev-cls "class" level. See
124 bt_event_class_set_specific_context_field_class()
125 bt_event_class_borrow_specific_context_field_class(),
126 and bt_event_class_borrow_specific_context_field_class_const()
128 Use bt_event_borrow_specific_context_field() and
129 bt_event_borrow_specific_context_field_const().
132 <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
134 Event's common context \bt_field.
136 The common context of an event contains contextual data of which the
137 layout is common to all the \bt_p_ev_cls of the
138 event's stream's \ref api-tir-stream-cls "class".
140 The \ref api-tir-fc "class" of an event's common context field is set
141 at the event's \bt_stream_cls level. See
142 bt_stream_class_set_event_common_context_field_class()
143 bt_stream_class_borrow_event_common_context_field_class(),
144 and bt_stream_class_borrow_event_common_context_field_class_const().
146 Use bt_event_borrow_common_context_field() and
147 bt_event_borrow_common_context_field_const().
158 @typedef struct bt_event bt_event;
173 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
176 Event of which to borrow the class.
179 \em Borrowed reference of the class of \bt_p{event}.
181 @bt_pre_not_null{event}
183 @sa bt_event_borrow_class_const() —
184 \c const version of this function.
186 extern bt_event_class
*bt_event_borrow_class(bt_event
*event
);
190 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
193 See bt_event_borrow_class().
195 extern const bt_event_class
*bt_event_borrow_class_const(
196 const bt_event
*event
);
207 Borrows the \bt_stream conceptually containing the event
211 Event of which to borrow the stream conceptually containing it.
214 \em Borrowed reference of the stream conceptually containing
217 @bt_pre_not_null{event}
219 @sa bt_event_borrow_stream_const() —
220 \c const version of this function.
222 extern bt_stream
*bt_event_borrow_stream(bt_event
*event
);
226 Borrows the \bt_stream conceptually containing the event
227 \bt_p{event} (\c const version).
229 See bt_event_borrow_stream().
231 extern const bt_stream
*bt_event_borrow_stream_const(
232 const bt_event
*event
);
243 Borrows the \bt_pkt conceptually containing the event
247 Only call this function if bt_stream_class_supports_packets()
248 returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
251 Event of which to borrow the packet conceptually containing it.
254 \em Borrowed reference of the packet conceptually containing
257 @bt_pre_not_null{event}
259 @sa bt_event_borrow_packet_const() —
260 \c const version of this function.
262 extern bt_packet
*bt_event_borrow_packet(bt_event
*event
);
266 Borrows the \bt_pkt conceptually containing the event
267 \bt_p{event} (\c const version).
269 See bt_event_borrow_packet().
271 extern const bt_packet
*bt_event_borrow_packet_const(
272 const bt_event
*event
);
283 Borrows the payload \bt_field of the event \bt_p{event}.
285 See the \ref api-tir-ev-prop-payload "payload field" property.
288 Event of which to borrow the payload field.
291 \em Borrowed reference of the payload field of \bt_p{event},
294 @bt_pre_not_null{event}
296 @sa bt_event_borrow_payload_field_const() —
297 \c const version of this function.
299 extern bt_field
*bt_event_borrow_payload_field(bt_event
*event
);
303 Borrows the payload \bt_field of the event \bt_p{event}
306 See bt_event_borrow_payload_field().
308 extern const bt_field
*bt_event_borrow_payload_field_const(
309 const bt_event
*event
);
313 Borrows the specific context \bt_field of the event \bt_p{event}.
315 See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
318 Event of which to borrow the specific context field.
321 \em Borrowed reference of the specific context field of
322 \bt_p{event}, or \c NULL if none.
324 @bt_pre_not_null{event}
326 @sa bt_event_borrow_specific_context_field_const() —
327 \c const version of this function.
330 bt_event_borrow_specific_context_field(bt_event
*event
);
334 Borrows the specific context \bt_field of the event \bt_p{event}
337 See bt_event_borrow_specific_context_field().
339 extern const bt_field
*bt_event_borrow_specific_context_field_const(
340 const bt_event
*event
);
344 Borrows the common context \bt_field of the event \bt_p{event}.
346 See the \ref api-tir-ev-prop-common-ctx "common context field" property.
349 Event of which to borrow the common context field.
352 \em Borrowed reference of the common context field of
353 \bt_p{event}, or \c NULL if none.
355 @bt_pre_not_null{event}
357 @sa bt_event_borrow_specific_context_field_const() —
358 \c const version of this function.
361 bt_event_borrow_common_context_field(bt_event
*event
);
365 Borrows the common context \bt_field of the event \bt_p{event}
368 See bt_event_borrow_common_context_field().
370 extern const bt_field
*bt_event_borrow_common_context_field_const(
371 const bt_event
*event
);
381 #endif /* BABELTRACE2_TRACE_IR_EVENT_H */
This page took 0.03654 seconds and 4 git commands to generate.