include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / trace-ir / event.h
CommitLineData
c057dea0 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
c057dea0 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
c057dea0
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_TRACE_IR_EVENT_H
8#define BABELTRACE2_TRACE_IR_EVENT_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
4fa90f32
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
3fadfbc0 16#include <babeltrace2/types.h>
b19ff26f 17
c057dea0
PP
18#ifdef __cplusplus
19extern "C" {
20#endif
21
43c59509
PP
22/*!
23@defgroup api-tir-ev Event
24@ingroup api-tir
25
26@brief
27 Trace event.
28
29An <strong><em>event</em></strong> represents a trace event record.
30
31An event is an instance of an \bt_ev_cls:
32
33@image html trace-structure.png
34
35In 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
45Borrow the class of an event with bt_event_borrow_class() and
46bt_event_borrow_class_const().
47
48An event is a \ref api-tir "trace IR" data object.
49
50You cannot directly create an event: there's no
51<code>bt_event_create()</code> function. The \bt_name library
52creates an event within an \bt_ev_msg from an \bt_ev_cls.
53Therefore, to fill the fields of an event, you must first
54borrow the event from an event message with
55bt_message_event_borrow_event().
56
57An event is a \ref api-fund-unique-object "unique object": it belongs to
58an \bt_ev_msg.
59
60Some library functions \ref api-fund-freezing "freeze" events on
61success. The documentation of those functions indicate this
62postcondition.
63
64The type of an event is #bt_event.
65
66An event conceptually belongs to a \bt_stream. Borrow the stream of an
67event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
68
69If the event's stream's class
70\ref api-tir-stream-cls-prop-supports-pkt "supports packets",
71the event also belongs to a \bt_pkt. In that case, borrow the packet of
72an event with bt_event_borrow_packet() and
73bt_event_borrow_packet_const().
74
75Because a stream or a packet could contain millions of events, there are
76no actual links from a stream or from a packet to its events.
77
78<h1>Properties</h1>
79
80An 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*/
4c81a2b7 172extern bt_event_class *bt_event_borrow_class(bt_event *event) __BT_NOEXCEPT;
56e18c4c 173
43c59509
PP
174/*!
175@brief
176 Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
177 (\c const version).
178
179See bt_event_borrow_class().
180*/
181extern const bt_event_class *bt_event_borrow_class_const(
4c81a2b7 182 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
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.
56e18c4c 198
43c59509
PP
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*/
4c81a2b7 208extern bt_stream *bt_event_borrow_stream(bt_event *event) __BT_NOEXCEPT;
56e18c4c 209
43c59509
PP
210/*!
211@brief
212 Borrows the \bt_stream conceptually containing the event
213 \bt_p{event} (\c const version).
214
215See bt_event_borrow_stream().
216*/
217extern const bt_stream *bt_event_borrow_stream_const(
4c81a2b7 218 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
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*/
4c81a2b7 248extern bt_packet *bt_event_borrow_packet(bt_event *event) __BT_NOEXCEPT;
43c59509
PP
249
250/*!
251@brief
252 Borrows the \bt_pkt conceptually containing the event
253 \bt_p{event} (\c const version).
254
255See bt_event_borrow_packet().
256*/
257extern const bt_packet *bt_event_borrow_packet_const(
4c81a2b7 258 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
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
271See 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}
c057dea0 281
43c59509
PP
282@sa bt_event_borrow_payload_field_const() &mdash;
283 \c const version of this function.
284*/
4c81a2b7 285extern bt_field *bt_event_borrow_payload_field(bt_event *event) __BT_NOEXCEPT;
43c59509
PP
286
287/*!
288@brief
289 Borrows the payload \bt_field of the event \bt_p{event}
290 (\c const version).
291
292See bt_event_borrow_payload_field().
293*/
294extern const bt_field *bt_event_borrow_payload_field_const(
4c81a2b7 295 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
296
297/*!
298@brief
299 Borrows the specific context \bt_field of the event \bt_p{event}.
300
301See 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*/
b19ff26f 315extern bt_field *
4c81a2b7 316bt_event_borrow_specific_context_field(bt_event *event) __BT_NOEXCEPT;
44c440bc 317
43c59509
PP
318/*!
319@brief
320 Borrows the specific context \bt_field of the event \bt_p{event}
321 (\c const version).
322
323See bt_event_borrow_specific_context_field().
324*/
325extern const bt_field *bt_event_borrow_specific_context_field_const(
4c81a2b7 326 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
327
328/*!
329@brief
330 Borrows the common context \bt_field of the event \bt_p{event}.
331
332See 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*/
346extern bt_field *
4c81a2b7 347bt_event_borrow_common_context_field(bt_event *event) __BT_NOEXCEPT;
43c59509
PP
348
349/*!
350@brief
351 Borrows the common context \bt_field of the event \bt_p{event}
352 (\c const version).
353
354See bt_event_borrow_common_context_field().
355*/
356extern const bt_field *bt_event_borrow_common_context_field_const(
4c81a2b7 357 const bt_event *event) __BT_NOEXCEPT;
43c59509
PP
358
359/*! @} */
360
361/*! @} */
094ff7c0 362
c057dea0
PP
363#ifdef __cplusplus
364}
365#endif
366
924dc299 367#endif /* BABELTRACE2_TRACE_IR_EVENT_H */
This page took 0.084481 seconds and 4 git commands to generate.