Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / trace-ir / field-path.h
1 #ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
2 #define BABELTRACE2_TRACE_IR_FIELD_PATH_H
3
4 /*
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
6 *
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.
24 */
25
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
28 #endif
29
30 #include <stdint.h>
31
32 #include <babeltrace2/types.h>
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /*!
39 @defgroup api-tir-field-path Field path
40 @ingroup api-tir
41
42 @brief
43 Path to a \bt_field.
44
45 A <strong><em>field path</em></strong> indicates how to reach a given
46 \bt_field from a given <em>root scope</em>.
47
48 More specifically, a field path indicates how to reach:
49
50 - The length field of a \bt_darray_field (with a length field).
51 - The selector field of a \bt_opt_field (with a selector field).
52 - The selector field of a \bt_var_field (with a selector field).
53
54 You can borrow the field path from the \ref api-tir-fc "classes" of such
55 fields with
56 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
57 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
58 and
59 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
60 Note that the field path properties of those field classes only becomes
61 available when the field class becomes part of an \bt_ev_cls or of a
62 \bt_stream_cls. See
63 \ref api-tir-fc-link "Field classes with links to other field classes".
64
65 A field path is a \ref api-tir "trace IR" metadata object.
66
67 A field path is a \ref api-fund-shared-object "shared object": get a
68 new reference with bt_field_path_get_ref() and put an existing
69 reference with bt_field_path_put_ref().
70
71 The type of a field path is #bt_field_path.
72
73 <h1>Properties</h1>
74
75 A field path has the following properties:
76
77 <dl>
78 <dt>
79 \anchor api-tir-field-path-prop-root
80 Root scope
81 </dt>
82 <dd>
83 Indicates from which \bt_struct_field to start a lookup.
84
85 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
86 learn more.
87
88 Get a field path's root scope with bt_field_path_get_root_scope().
89 </dd>
90
91 <dt>
92 \anchor api-tir-field-path-prop-items
93 Items
94 </dt>
95 <dd>
96 Each item in a field path's item list indicates which action to take
97 to follow the path to the linked \bt_field.
98
99 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
100 learn more.
101
102 Get the number of items in a field path with
103 bt_field_path_get_item_count().
104
105 Borrow an item from a field path with
106 bt_field_path_borrow_item_by_index_const(). This function
107 returns the #bt_field_path_item type.
108
109 A field path item is a \ref api-fund-unique-object "unique object":
110 it belongs to the field path which contains it.
111 </dd>
112 </dl>
113
114 <h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
115
116 The field resolution algorithm using a field path is:
117
118 -# Use the appropriate function to set a <em>current field</em> variable
119 from the root scope (as returned by bt_field_path_get_root_scope()):
120
121 <dl>
122 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
123 <dd>
124 bt_packet_borrow_context_field_const().
125 </dd>
126 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
127 <dd>
128 bt_event_borrow_common_context_field_const().
129 </dd>
130 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
131 <dd>
132 bt_event_borrow_specific_context_field_const().
133 </dd>
134 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
135 <dd>
136 bt_event_borrow_payload_field_const().
137 </dd>
138 </dl>
139
140 -# For each field path item (use bt_field_path_get_item_count()
141 and bt_field_path_borrow_item_by_index_const()), depending on
142 the item's type (as returned by bt_field_path_item_get_type()):
143
144 <dl>
145 <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
146 <dd>
147 Call bt_field_path_item_index_get_index() to get the item's
148 index value.
149
150 Depending on the current field's class's type (as
151 returned by bt_field_get_class_type()):
152
153 <dl>
154 <dt>\bt_c_struct_fc</dt>
155 <dd>
156 Call bt_field_structure_borrow_member_field_by_index_const()
157 with the current field and with the item's index to set the
158 new current field.
159 </dd>
160
161 <dt>\bt_c_var_fc</dt>
162 <dd>
163 Call bt_field_variant_borrow_selected_option_field_const()
164 with the current field to set the new current field.
165 </dd>
166 </dl>
167 </dd>
168
169 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
170 <dd>
171 Call bt_field_array_borrow_element_field_by_index_const()
172 with the index of the field eventually containing the
173 field with a link (\bt_darray_field, \bt_opt_field, or
174 \bt_var_field) and the current field to set the new current
175 field.
176 </dd>
177
178 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
179 <dd>
180 Call bt_field_option_borrow_field_const() with the current
181 field to set the new current field.
182 </dd>
183 </dl>
184
185 After applying this procedure, the current field is the linked
186 field.
187 */
188
189 /*! @{ */
190
191 /*!
192 @name Field path
193 @{
194
195 @typedef struct bt_field_path bt_field_path;
196
197 @brief
198 Field path.
199
200 */
201
202 /*!
203 @brief
204 Field path scopes.
205 */
206 typedef enum bt_field_path_scope {
207 /*!
208 @brief
209 Packet context.
210 */
211 BT_FIELD_PATH_SCOPE_PACKET_CONTEXT = 0,
212
213 /*!
214 @brief
215 Event common context.
216 */
217 BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT = 1,
218
219 /*!
220 @brief
221 Event specific context.
222 */
223 BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT = 2,
224
225 /*!
226 @brief
227 Event payload.
228 */
229 BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD = 3,
230 } bt_field_path_scope;
231
232 /*!
233 @brief
234 Returns the root scope of the field path \bt_p{field_path}.
235
236 See the \ref api-tir-field-path-prop-root "root scope" property.
237
238 @param[in] field_path
239 Field path of which to get the root scope.
240
241 @returns
242 Root scope of \bt_p{field_path}.
243
244 @bt_pre_not_null{field_path}
245 */
246 extern bt_field_path_scope bt_field_path_get_root_scope(
247 const bt_field_path *field_path);
248
249 /*!
250 @brief
251 Returns the number of items contained in the field path
252 \bt_p{field_path}.
253
254 See the \ref api-tir-field-path-prop-items "items" property.
255
256 @param[in] field_path
257 Field path of which to get the number of contained items.
258
259 @returns
260 Number of contained items in \bt_p{field_path}.
261
262 @bt_pre_not_null{field_path}
263 */
264 extern uint64_t bt_field_path_get_item_count(
265 const bt_field_path *field_path);
266
267 /*!
268 @brief
269 Borrows the item at index \bt_p{index} from the
270 field path \bt_p{field_path}.
271
272 See the \ref api-tir-field-path-prop-items "items" property.
273
274 @param[in] field_path
275 Field path from which to borrow the item at index \bt_p{index}.
276 @param[in] index
277 Index of the item to borrow from \bt_p{field_path}.
278
279 @returns
280 @parblock
281 \em Borrowed reference of the item of
282 \bt_p{field_path} at index \bt_p{index}.
283
284 The returned pointer remains valid as long as \bt_p{field_path}
285 exists.
286 @endparblock
287
288 @bt_pre_not_null{field_path}
289 @pre
290 \bt_p{index} is less than the number of items in
291 \bt_p{field_path} (as returned by bt_field_path_get_item_count()).
292
293 @sa bt_field_path_get_item_count() &mdash;
294 Returns the number of items contained in a field path.
295 */
296 extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
297 const bt_field_path *field_path, uint64_t index);
298
299 /*!
300 @brief
301 Increments the \ref api-fund-shared-object "reference count" of
302 the field path \bt_p{field_path}.
303
304 @param[in] field_path
305 @parblock
306 Field path of which to increment the reference count.
307
308 Can be \c NULL.
309 @endparblock
310
311 @sa bt_field_path_put_ref() &mdash;
312 Decrements the reference count of a field path.
313 */
314 extern void bt_field_path_get_ref(const bt_field_path *field_path);
315
316 /*!
317 @brief
318 Decrements the \ref api-fund-shared-object "reference count" of
319 the field path \bt_p{field_path}.
320
321 @param[in] field_path
322 @parblock
323 Field path of which to decrement the reference count.
324
325 Can be \c NULL.
326 @endparblock
327
328 @sa bt_field_path_get_ref() &mdash;
329 Increments the reference count of a field path.
330 */
331 extern void bt_field_path_put_ref(const bt_field_path *field_path);
332
333 /*!
334 @brief
335 Decrements the reference count of the field path
336 \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
337
338 @param _field_path
339 @parblock
340 Field path of which to decrement the reference count.
341
342 Can contain \c NULL.
343 @endparblock
344
345 @bt_pre_assign_expr{_field_path}
346 */
347 #define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path) \
348 do { \
349 bt_field_path_put_ref(_field_path); \
350 (_field_path) = NULL; \
351 } while (0)
352
353 /*!
354 @brief
355 Decrements the reference count of the field path \bt_p{_dst}, sets
356 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
357
358 This macro effectively moves a field path reference from the expression
359 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
360 \bt_p{_dst} reference.
361
362 @param _dst
363 @parblock
364 Destination expression.
365
366 Can contain \c NULL.
367 @endparblock
368 @param _src
369 @parblock
370 Source expression.
371
372 Can contain \c NULL.
373 @endparblock
374
375 @bt_pre_assign_expr{_dst}
376 @bt_pre_assign_expr{_src}
377 */
378 #define BT_FIELD_PATH_MOVE_REF(_dst, _src) \
379 do { \
380 bt_field_path_put_ref(_dst); \
381 (_dst) = (_src); \
382 (_src) = NULL; \
383 } while (0)
384
385 /*! @} */
386
387 /*!
388 @name Field path item
389 @{
390
391 @typedef struct bt_field_path_item bt_field_path_item;
392
393 @brief
394 Field path item.
395
396 */
397
398 /*!
399 @brief
400 Field path item type enumerators.
401 */
402 typedef enum bt_field_path_item_type {
403 /*!
404 @brief
405 Index of a \bt_struct_field member or selected \bt_var_field
406 option's field.
407 */
408 BT_FIELD_PATH_ITEM_TYPE_INDEX = 1 << 0,
409
410 /*!
411 @brief
412 Common field of an \bt_array_field.
413 */
414 BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT = 1 << 1,
415
416 /*!
417 @brief
418 Current field of an \bt_opt_field.
419 */
420 BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT = 1 << 2,
421 } bt_field_path_item_type;
422
423 /*!
424 @brief
425 Returns the type enumerator of the field path item
426 \bt_p{item}.
427
428 See the \ref api-tir-field-path-prop-items "items" property.
429
430 @param[in] item
431 Field path item of which to get the type enumerator
432
433 @returns
434 Type enumerator of \bt_p{item}.
435
436 @bt_pre_not_null{item}
437 */
438 extern bt_field_path_item_type bt_field_path_item_get_type(
439 const bt_field_path_item *item);
440
441 /*!
442 @brief
443 Returns the index value of the index field path item
444 \bt_p{item}.
445
446 See the \ref api-tir-field-path-prop-items "items" property.
447
448 @param[in] item
449 Index field path item of which to get the index value.
450
451 @returns
452 Index value of \bt_p{item}.
453
454 @bt_pre_not_null{item}
455 @pre
456 \bt_p{item} is an index field path item
457 (bt_field_path_item_get_type() returns
458 #BT_FIELD_PATH_ITEM_TYPE_INDEX).
459 */
460 extern uint64_t bt_field_path_item_index_get_index(
461 const bt_field_path_item *item);
462
463 /*! @} */
464
465 /*! @} */
466
467 #ifdef __cplusplus
468 }
469 #endif
470
471 #endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */
This page took 0.046834 seconds and 4 git commands to generate.