Commit | Line | Data |
---|---|---|
3fd40f46 PP |
1 | #ifndef BABELTRACE2_TRACE_IR_EVENT_H |
2 | #define BABELTRACE2_TRACE_IR_EVENT_H | |
a62f9ba0 PP |
3 | |
4 | /* | |
0dcb770f | 5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation |
a62f9ba0 | 6 | * |
a62f9ba0 PP |
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: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in | |
15 | * all copies or substantial portions of the Software. | |
16 | * | |
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 | |
23 | * SOFTWARE. | |
a62f9ba0 PP |
24 | */ |
25 | ||
9df34b44 PP |
26 | #ifndef __BT_IN_BABELTRACE_H |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
71c5da58 | 30 | #include <babeltrace2/types.h> |
8eee8ea2 | 31 | |
a62f9ba0 PP |
32 | #ifdef __cplusplus |
33 | extern "C" { | |
34 | #endif | |
35 | ||
7704a0af PP |
36 | /*! |
37 | @defgroup api-tir-ev Event | |
38 | @ingroup api-tir | |
39 | ||
40 | @brief | |
41 | Trace event. | |
42 | ||
43 | An <strong><em>event</em></strong> represents a trace event record. | |
44 | ||
45 | An event is an instance of an \bt_ev_cls: | |
46 | ||
47 | @image html trace-structure.png | |
48 | ||
49 | In the illustration above, notice that: | |
50 | ||
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. | |
58 | ||
59 | Borrow the class of an event with bt_event_borrow_class() and | |
60 | bt_event_borrow_class_const(). | |
61 | ||
62 | An event is a \ref api-tir "trace IR" data object. | |
63 | ||
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(). | |
70 | ||
71 | An event is a \ref api-fund-unique-object "unique object": it belongs to | |
72 | an \bt_ev_msg. | |
73 | ||
74 | Some library functions \ref api-fund-freezing "freeze" events on | |
75 | success. The documentation of those functions indicate this | |
76 | postcondition. | |
77 | ||
78 | The type of an event is #bt_event. | |
79 | ||
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(). | |
82 | ||
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(). | |
88 | ||
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. | |
91 | ||
92 | <h1>Properties</h1> | |
93 | ||
94 | An event has the following properties: | |
95 | ||
96 | <dl> | |
97 | <dt>\anchor api-tir-ev-prop-payload Payload field</dt> | |
98 | <dd> | |
99 | Event's payload \bt_field. | |
100 | ||
101 | The payload of an event contains its main trace data. | |
102 | ||
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(). | |
108 | ||
109 | Use bt_event_borrow_payload_field() and | |
110 | bt_event_borrow_payload_field_const(). | |
111 | </dd> | |
112 | ||
113 | <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt> | |
114 | <dd> | |
115 | Event's specific context \bt_field. | |
116 | ||
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 | |
120 | payload. | |
121 | ||
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() | |
127 | ||
128 | Use bt_event_borrow_specific_context_field() and | |
129 | bt_event_borrow_specific_context_field_const(). | |
130 | </dd> | |
131 | ||
132 | <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt> | |
133 | <dd> | |
134 | Event's common context \bt_field. | |
135 | ||
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". | |
139 | ||
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(). | |
145 | ||
146 | Use bt_event_borrow_common_context_field() and | |
147 | bt_event_borrow_common_context_field_const(). | |
148 | </dd> | |
149 | </dl> | |
150 | */ | |
151 | ||
152 | /*! @{ */ | |
153 | ||
154 | /*! | |
155 | @name Type | |
156 | @{ | |
157 | ||
158 | @typedef struct bt_event bt_event; | |
159 | ||
160 | @brief | |
161 | Event. | |
162 | ||
163 | @} | |
164 | */ | |
165 | ||
166 | /*! | |
167 | @name Class access | |
168 | @{ | |
169 | */ | |
170 | ||
171 | /*! | |
172 | @brief | |
173 | Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}. | |
174 | ||
175 | @param[in] event | |
176 | Event of which to borrow the class. | |
177 | ||
178 | @returns | |
179 | \em Borrowed reference of the class of \bt_p{event}. | |
180 | ||
181 | @bt_pre_not_null{event} | |
182 | ||
183 | @sa bt_event_borrow_class_const() — | |
184 | \c const version of this function. | |
185 | */ | |
8eee8ea2 | 186 | extern bt_event_class *bt_event_borrow_class(bt_event *event); |
108b91d0 | 187 | |
7704a0af PP |
188 | /*! |
189 | @brief | |
190 | Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event} | |
191 | (\c const version). | |
192 | ||
193 | See bt_event_borrow_class(). | |
194 | */ | |
195 | extern const bt_event_class *bt_event_borrow_class_const( | |
196 | const bt_event *event); | |
197 | ||
198 | /*! @} */ | |
199 | ||
200 | /*! | |
201 | @name Stream access | |
202 | @{ | |
203 | */ | |
204 | ||
205 | /*! | |
206 | @brief | |
207 | Borrows the \bt_stream conceptually containing the event | |
208 | \bt_p{event}. | |
209 | ||
210 | @param[in] event | |
211 | Event of which to borrow the stream conceptually containing it. | |
108b91d0 | 212 | |
7704a0af PP |
213 | @returns |
214 | \em Borrowed reference of the stream conceptually containing | |
215 | \bt_p{event}. | |
216 | ||
217 | @bt_pre_not_null{event} | |
218 | ||
219 | @sa bt_event_borrow_stream_const() — | |
220 | \c const version of this function. | |
221 | */ | |
8eee8ea2 | 222 | extern bt_stream *bt_event_borrow_stream(bt_event *event); |
108b91d0 | 223 | |
7704a0af PP |
224 | /*! |
225 | @brief | |
226 | Borrows the \bt_stream conceptually containing the event | |
227 | \bt_p{event} (\c const version). | |
228 | ||
229 | See bt_event_borrow_stream(). | |
230 | */ | |
231 | extern const bt_stream *bt_event_borrow_stream_const( | |
232 | const bt_event *event); | |
233 | ||
234 | /*! @} */ | |
235 | ||
236 | /*! | |
237 | @name Packet access | |
238 | @{ | |
239 | */ | |
240 | ||
241 | /*! | |
242 | @brief | |
243 | Borrows the \bt_pkt conceptually containing the event | |
244 | \bt_p{event}. | |
245 | ||
246 | @attention | |
247 | Only call this function if bt_stream_class_supports_packets() | |
248 | returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}. | |
249 | ||
250 | @param[in] event | |
251 | Event of which to borrow the packet conceptually containing it. | |
252 | ||
253 | @returns | |
254 | \em Borrowed reference of the packet conceptually containing | |
255 | \bt_p{event}. | |
256 | ||
257 | @bt_pre_not_null{event} | |
258 | ||
259 | @sa bt_event_borrow_packet_const() — | |
260 | \c const version of this function. | |
261 | */ | |
262 | extern bt_packet *bt_event_borrow_packet(bt_event *event); | |
263 | ||
264 | /*! | |
265 | @brief | |
266 | Borrows the \bt_pkt conceptually containing the event | |
267 | \bt_p{event} (\c const version). | |
268 | ||
269 | See bt_event_borrow_packet(). | |
270 | */ | |
271 | extern const bt_packet *bt_event_borrow_packet_const( | |
272 | const bt_event *event); | |
273 | ||
274 | /*! @} */ | |
275 | ||
276 | /*! | |
277 | @name Properties | |
278 | @{ | |
279 | */ | |
280 | ||
281 | /*! | |
282 | @brief | |
283 | Borrows the payload \bt_field of the event \bt_p{event}. | |
284 | ||
285 | See the \ref api-tir-ev-prop-payload "payload field" property. | |
286 | ||
287 | @param[in] event | |
288 | Event of which to borrow the payload field. | |
289 | ||
290 | @returns | |
291 | \em Borrowed reference of the payload field of \bt_p{event}, | |
292 | or \c NULL if none. | |
293 | ||
294 | @bt_pre_not_null{event} | |
a62f9ba0 | 295 | |
7704a0af PP |
296 | @sa bt_event_borrow_payload_field_const() — |
297 | \c const version of this function. | |
298 | */ | |
299 | extern bt_field *bt_event_borrow_payload_field(bt_event *event); | |
300 | ||
301 | /*! | |
302 | @brief | |
303 | Borrows the payload \bt_field of the event \bt_p{event} | |
304 | (\c const version). | |
305 | ||
306 | See bt_event_borrow_payload_field(). | |
307 | */ | |
308 | extern const bt_field *bt_event_borrow_payload_field_const( | |
309 | const bt_event *event); | |
310 | ||
311 | /*! | |
312 | @brief | |
313 | Borrows the specific context \bt_field of the event \bt_p{event}. | |
314 | ||
315 | See the \ref api-tir-ev-prop-spec-ctx "specific context field" property. | |
316 | ||
317 | @param[in] event | |
318 | Event of which to borrow the specific context field. | |
319 | ||
320 | @returns | |
321 | \em Borrowed reference of the specific context field of | |
322 | \bt_p{event}, or \c NULL if none. | |
323 | ||
324 | @bt_pre_not_null{event} | |
325 | ||
326 | @sa bt_event_borrow_specific_context_field_const() — | |
327 | \c const version of this function. | |
328 | */ | |
8eee8ea2 PP |
329 | extern bt_field * |
330 | bt_event_borrow_specific_context_field(bt_event *event); | |
7b33a0e0 | 331 | |
7704a0af PP |
332 | /*! |
333 | @brief | |
334 | Borrows the specific context \bt_field of the event \bt_p{event} | |
335 | (\c const version). | |
336 | ||
337 | See bt_event_borrow_specific_context_field(). | |
338 | */ | |
339 | extern const bt_field *bt_event_borrow_specific_context_field_const( | |
340 | const bt_event *event); | |
341 | ||
342 | /*! | |
343 | @brief | |
344 | Borrows the common context \bt_field of the event \bt_p{event}. | |
345 | ||
346 | See the \ref api-tir-ev-prop-common-ctx "common context field" property. | |
347 | ||
348 | @param[in] event | |
349 | Event of which to borrow the common context field. | |
350 | ||
351 | @returns | |
352 | \em Borrowed reference of the common context field of | |
353 | \bt_p{event}, or \c NULL if none. | |
354 | ||
355 | @bt_pre_not_null{event} | |
356 | ||
357 | @sa bt_event_borrow_specific_context_field_const() — | |
358 | \c const version of this function. | |
359 | */ | |
360 | extern bt_field * | |
361 | bt_event_borrow_common_context_field(bt_event *event); | |
362 | ||
363 | /*! | |
364 | @brief | |
365 | Borrows the common context \bt_field of the event \bt_p{event} | |
366 | (\c const version). | |
367 | ||
368 | See bt_event_borrow_common_context_field(). | |
369 | */ | |
370 | extern const bt_field *bt_event_borrow_common_context_field_const( | |
371 | const bt_event *event); | |
372 | ||
373 | /*! @} */ | |
374 | ||
375 | /*! @} */ | |
5fe68922 | 376 | |
a62f9ba0 PP |
377 | #ifdef __cplusplus |
378 | } | |
379 | #endif | |
380 | ||
3fd40f46 | 381 | #endif /* BABELTRACE2_TRACE_IR_EVENT_H */ |