2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
8 #define BABELTRACE2_TRACE_IR_FIELD_PATH_H
10 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-field-path Field path
29 A <strong><em>field path</em></strong> indicates how to reach a given
30 \bt_field from a given <em>root scope</em>.
32 More specifically, a field path indicates how to reach:
34 - The length field of a \bt_darray_field (with a length field).
35 - The selector field of a \bt_opt_field (with a selector field).
36 - The selector field of a \bt_var_field (with a selector field).
38 You can borrow the field path from the \ref api-tir-fc "classes" of such
40 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
41 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
43 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
44 Note that the field path properties of those field classes only becomes
45 available when the field class becomes part of an \bt_ev_cls or of a
47 \ref api-tir-fc-link "Field classes with links to other field classes".
49 A field path is a \ref api-tir "trace IR" metadata object.
51 A field path is a \ref api-fund-shared-object "shared object": get a
52 new reference with bt_field_path_get_ref() and put an existing
53 reference with bt_field_path_put_ref().
55 The type of a field path is #bt_field_path.
59 A field path has the following properties:
63 \anchor api-tir-field-path-prop-root
67 Indicates from which \bt_struct_field to start a lookup.
69 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
72 Get a field path's root scope with bt_field_path_get_root_scope().
76 \anchor api-tir-field-path-prop-items
80 Each item in a field path's item list indicates which action to take
81 to follow the path to the linked \bt_field.
83 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
86 Get the number of items in a field path with
87 bt_field_path_get_item_count().
89 Borrow an item from a field path with
90 bt_field_path_borrow_item_by_index_const(). This function
91 returns the #bt_field_path_item type.
93 A field path item is a \ref api-fund-unique-object "unique object":
94 it belongs to the field path which contains it.
98 <h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
100 The field resolution algorithm using a field path is:
102 -# Use the appropriate function to set a <em>current field</em> variable
103 from the root scope (as returned by bt_field_path_get_root_scope()):
106 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
108 bt_packet_borrow_context_field_const().
110 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
112 bt_event_borrow_common_context_field_const().
114 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
116 bt_event_borrow_specific_context_field_const().
118 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
120 bt_event_borrow_payload_field_const().
124 -# For each field path item (use bt_field_path_get_item_count()
125 and bt_field_path_borrow_item_by_index_const()), depending on
126 the item's type (as returned by bt_field_path_item_get_type()):
129 <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
131 Call bt_field_path_item_index_get_index() to get the item's
134 Depending on the current field's class's type (as
135 returned by bt_field_get_class_type()):
138 <dt>\bt_c_struct_fc</dt>
140 Call bt_field_structure_borrow_member_field_by_index_const()
141 with the current field and with the item's index to set the
145 <dt>\bt_c_var_fc</dt>
147 Call bt_field_variant_borrow_selected_option_field_const()
148 with the current field to set the new current field.
153 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
155 Call bt_field_array_borrow_element_field_by_index_const()
156 with the index of the field eventually containing the
157 field with a link (\bt_darray_field, \bt_opt_field, or
158 \bt_var_field) and the current field to set the new current
162 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
164 Call bt_field_option_borrow_field_const() with the current
165 field to set the new current field.
169 After applying this procedure, the current field is the linked
179 @typedef struct bt_field_path bt_field_path;
190 typedef enum bt_field_path_scope
{
195 BT_FIELD_PATH_SCOPE_PACKET_CONTEXT
= 0,
199 Event common context.
201 BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT
= 1,
205 Event specific context.
207 BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT
= 2,
213 BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD
= 3,
214 } bt_field_path_scope
;
218 Returns the root scope of the field path \bt_p{field_path}.
220 See the \ref api-tir-field-path-prop-root "root scope" property.
222 @param[in] field_path
223 Field path of which to get the root scope.
226 Root scope of \bt_p{field_path}.
228 @bt_pre_not_null{field_path}
230 extern bt_field_path_scope
bt_field_path_get_root_scope(
231 const bt_field_path
*field_path
);
235 Returns the number of items contained in the field path
238 See the \ref api-tir-field-path-prop-items "items" property.
240 @param[in] field_path
241 Field path of which to get the number of contained items.
244 Number of contained items in \bt_p{field_path}.
246 @bt_pre_not_null{field_path}
248 extern uint64_t bt_field_path_get_item_count(
249 const bt_field_path
*field_path
);
253 Borrows the item at index \bt_p{index} from the
254 field path \bt_p{field_path}.
256 See the \ref api-tir-field-path-prop-items "items" property.
258 @param[in] field_path
259 Field path from which to borrow the item at index \bt_p{index}.
261 Index of the item to borrow from \bt_p{field_path}.
265 \em Borrowed reference of the item of
266 \bt_p{field_path} at index \bt_p{index}.
268 The returned pointer remains valid as long as \bt_p{field_path}
272 @bt_pre_not_null{field_path}
274 \bt_p{index} is less than the number of items in
275 \bt_p{field_path} (as returned by bt_field_path_get_item_count()).
277 @sa bt_field_path_get_item_count() —
278 Returns the number of items contained in a field path.
280 extern const bt_field_path_item
*bt_field_path_borrow_item_by_index_const(
281 const bt_field_path
*field_path
, uint64_t index
);
285 Increments the \ref api-fund-shared-object "reference count" of
286 the field path \bt_p{field_path}.
288 @param[in] field_path
290 Field path of which to increment the reference count.
295 @sa bt_field_path_put_ref() —
296 Decrements the reference count of a field path.
298 extern void bt_field_path_get_ref(const bt_field_path
*field_path
);
302 Decrements the \ref api-fund-shared-object "reference count" of
303 the field path \bt_p{field_path}.
305 @param[in] field_path
307 Field path of which to decrement the reference count.
312 @sa bt_field_path_get_ref() —
313 Increments the reference count of a field path.
315 extern void bt_field_path_put_ref(const bt_field_path
*field_path
);
319 Decrements the reference count of the field path
320 \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
324 Field path of which to decrement the reference count.
329 @bt_pre_assign_expr{_field_path}
331 #define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path) \
333 bt_field_path_put_ref(_field_path); \
334 (_field_path) = NULL; \
339 Decrements the reference count of the field path \bt_p{_dst}, sets
340 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
342 This macro effectively moves a field path reference from the expression
343 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
344 \bt_p{_dst} reference.
348 Destination expression.
359 @bt_pre_assign_expr{_dst}
360 @bt_pre_assign_expr{_src}
362 #define BT_FIELD_PATH_MOVE_REF(_dst, _src) \
364 bt_field_path_put_ref(_dst); \
372 @name Field path item
375 @typedef struct bt_field_path_item bt_field_path_item;
384 Field path item type enumerators.
386 typedef enum bt_field_path_item_type
{
389 Index of a \bt_struct_field member or selected \bt_var_field
392 BT_FIELD_PATH_ITEM_TYPE_INDEX
= 1 << 0,
396 Common field of an \bt_array_field.
398 BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT
= 1 << 1,
402 Current field of an \bt_opt_field.
404 BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT
= 1 << 2,
405 } bt_field_path_item_type
;
409 Returns the type enumerator of the field path item
412 See the \ref api-tir-field-path-prop-items "items" property.
415 Field path item of which to get the type enumerator
418 Type enumerator of \bt_p{item}.
420 @bt_pre_not_null{item}
422 extern bt_field_path_item_type
bt_field_path_item_get_type(
423 const bt_field_path_item
*item
);
427 Returns the index value of the index field path item
430 See the \ref api-tir-field-path-prop-items "items" property.
433 Index field path item of which to get the index value.
436 Index value of \bt_p{item}.
438 @bt_pre_not_null{item}
440 \bt_p{item} is an index field path item
441 (bt_field_path_item_get_type() returns
442 #BT_FIELD_PATH_ITEM_TYPE_INDEX).
444 extern uint64_t bt_field_path_item_index_get_index(
445 const bt_field_path_item
*item
);
455 #endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */