c571ca0bff23d01164b8bad9255e966273c8d2a6
[babeltrace.git] / include / babeltrace2 / trace-ir / event.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_TRACE_IR_EVENT_H
8 #define BABELTRACE2_TRACE_IR_EVENT_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #include <babeltrace2/types.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /*!
23 @defgroup api-tir-ev Event
24 @ingroup api-tir
25
26 @brief
27 Trace event.
28
29 An <strong><em>event</em></strong> represents a trace event record.
30
31 An event is an instance of an \bt_ev_cls:
32
33 @image html trace-structure.png
34
35 In the illustration above, notice that:
36
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.
44
45 Borrow the class of an event with bt_event_borrow_class() and
46 bt_event_borrow_class_const().
47
48 An event is a \ref api-tir "trace IR" data object.
49
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().
56
57 An event is a \ref api-fund-unique-object "unique object": it belongs to
58 an \bt_ev_msg.
59
60 Some library functions \ref api-fund-freezing "freeze" events on
61 success. The documentation of those functions indicate this
62 postcondition.
63
64 The type of an event is #bt_event.
65
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().
68
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().
74
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.
77
78 <h1>Properties</h1>
79
80 An event has the following properties:
81
82 <dl>
83 <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
84 <dd>
85 Event's payload \bt_field.
86
87 The payload of an event contains its main trace data.
88
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().
94
95 Use bt_event_borrow_payload_field() and
96 bt_event_borrow_payload_field_const().
97 </dd>
98
99 <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
100 <dd>
101 Event's specific context \bt_field.
102
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
106 payload.
107
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()
113
114 Use bt_event_borrow_specific_context_field() and
115 bt_event_borrow_specific_context_field_const().
116 </dd>
117
118 <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
119 <dd>
120 Event's common context \bt_field.
121
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".
125
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().
131
132 Use bt_event_borrow_common_context_field() and
133 bt_event_borrow_common_context_field_const().
134 </dd>
135 </dl>
136 */
137
138 /*! @{ */
139
140 /*!
141 @name Type
142 @{
143
144 @typedef struct bt_event bt_event;
145
146 @brief
147 Event.
148
149 @}
150 */
151
152 /*!
153 @name Class access
154 @{
155 */
156
157 /*!
158 @brief
159 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
160
161 @param[in] event
162 Event of which to borrow the class.
163
164 @returns
165 \em Borrowed reference of the class of \bt_p{event}.
166
167 @bt_pre_not_null{event}
168
169 @sa bt_event_borrow_class_const() &mdash;
170 \c const version of this function.
171 */
172 extern bt_event_class *bt_event_borrow_class(bt_event *event);
173
174 /*!
175 @brief
176 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
177 (\c const version).
178
179 See bt_event_borrow_class().
180 */
181 extern const bt_event_class *bt_event_borrow_class_const(
182 const bt_event *event);
183
184 /*! @} */
185
186 /*!
187 @name Stream access
188 @{
189 */
190
191 /*!
192 @brief
193 Borrows the \bt_stream conceptually containing the event
194 \bt_p{event}.
195
196 @param[in] event
197 Event of which to borrow the stream conceptually containing it.
198
199 @returns
200 \em Borrowed reference of the stream conceptually containing
201 \bt_p{event}.
202
203 @bt_pre_not_null{event}
204
205 @sa bt_event_borrow_stream_const() &mdash;
206 \c const version of this function.
207 */
208 extern bt_stream *bt_event_borrow_stream(bt_event *event);
209
210 /*!
211 @brief
212 Borrows the \bt_stream conceptually containing the event
213 \bt_p{event} (\c const version).
214
215 See bt_event_borrow_stream().
216 */
217 extern const bt_stream *bt_event_borrow_stream_const(
218 const bt_event *event);
219
220 /*! @} */
221
222 /*!
223 @name Packet access
224 @{
225 */
226
227 /*!
228 @brief
229 Borrows the \bt_pkt conceptually containing the event
230 \bt_p{event}.
231
232 @attention
233 Only call this function if bt_stream_class_supports_packets()
234 returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
235
236 @param[in] event
237 Event of which to borrow the packet conceptually containing it.
238
239 @returns
240 \em Borrowed reference of the packet conceptually containing
241 \bt_p{event}.
242
243 @bt_pre_not_null{event}
244
245 @sa bt_event_borrow_packet_const() &mdash;
246 \c const version of this function.
247 */
248 extern bt_packet *bt_event_borrow_packet(bt_event *event);
249
250 /*!
251 @brief
252 Borrows the \bt_pkt conceptually containing the event
253 \bt_p{event} (\c const version).
254
255 See bt_event_borrow_packet().
256 */
257 extern const bt_packet *bt_event_borrow_packet_const(
258 const bt_event *event);
259
260 /*! @} */
261
262 /*!
263 @name Properties
264 @{
265 */
266
267 /*!
268 @brief
269 Borrows the payload \bt_field of the event \bt_p{event}.
270
271 See the \ref api-tir-ev-prop-payload "payload field" property.
272
273 @param[in] event
274 Event of which to borrow the payload field.
275
276 @returns
277 \em Borrowed reference of the payload field of \bt_p{event},
278 or \c NULL if none.
279
280 @bt_pre_not_null{event}
281
282 @sa bt_event_borrow_payload_field_const() &mdash;
283 \c const version of this function.
284 */
285 extern bt_field *bt_event_borrow_payload_field(bt_event *event);
286
287 /*!
288 @brief
289 Borrows the payload \bt_field of the event \bt_p{event}
290 (\c const version).
291
292 See bt_event_borrow_payload_field().
293 */
294 extern const bt_field *bt_event_borrow_payload_field_const(
295 const bt_event *event);
296
297 /*!
298 @brief
299 Borrows the specific context \bt_field of the event \bt_p{event}.
300
301 See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
302
303 @param[in] event
304 Event of which to borrow the specific context field.
305
306 @returns
307 \em Borrowed reference of the specific context field of
308 \bt_p{event}, or \c NULL if none.
309
310 @bt_pre_not_null{event}
311
312 @sa bt_event_borrow_specific_context_field_const() &mdash;
313 \c const version of this function.
314 */
315 extern bt_field *
316 bt_event_borrow_specific_context_field(bt_event *event);
317
318 /*!
319 @brief
320 Borrows the specific context \bt_field of the event \bt_p{event}
321 (\c const version).
322
323 See bt_event_borrow_specific_context_field().
324 */
325 extern const bt_field *bt_event_borrow_specific_context_field_const(
326 const bt_event *event);
327
328 /*!
329 @brief
330 Borrows the common context \bt_field of the event \bt_p{event}.
331
332 See the \ref api-tir-ev-prop-common-ctx "common context field" property.
333
334 @param[in] event
335 Event of which to borrow the common context field.
336
337 @returns
338 \em Borrowed reference of the common context field of
339 \bt_p{event}, or \c NULL if none.
340
341 @bt_pre_not_null{event}
342
343 @sa bt_event_borrow_specific_context_field_const() &mdash;
344 \c const version of this function.
345 */
346 extern bt_field *
347 bt_event_borrow_common_context_field(bt_event *event);
348
349 /*!
350 @brief
351 Borrows the common context \bt_field of the event \bt_p{event}
352 (\c const version).
353
354 See bt_event_borrow_common_context_field().
355 */
356 extern const bt_field *bt_event_borrow_common_context_field_const(
357 const bt_event *event);
358
359 /*! @} */
360
361 /*! @} */
362
363 #ifdef __cplusplus
364 }
365 #endif
366
367 #endif /* BABELTRACE2_TRACE_IR_EVENT_H */
This page took 0.036614 seconds and 3 git commands to generate.