1 #ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
2 #define BABELTRACE2_TRACE_IR_FIELD_PATH_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
39 @defgroup api-tir-field-path Field path
45 A <strong><em>field path</em></strong> indicates how to reach a given
46 \bt_field from a given <em>root scope</em>.
48 More specifically, a field path indicates how to reach:
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).
54 You can borrow the field path from the \ref api-tir-fc "classes" of such
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(),
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
63 \ref api-tir-fc-link "Field classes with links to other field classes".
65 A field path is a \ref api-tir "trace IR" metadata object.
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().
71 The type of a field path is #bt_field_path.
75 A field path has the following properties:
79 \anchor api-tir-field-path-prop-root
83 Indicates from which \bt_struct_field to start a lookup.
85 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
88 Get a field path's root scope with bt_field_path_get_root_scope().
92 \anchor api-tir-field-path-prop-items
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.
99 See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
102 Get the number of items in a field path with
103 bt_field_path_get_item_count().
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.
109 A field path item is a \ref api-fund-unique-object "unique object":
110 it belongs to the field path which contains it.
114 <h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
116 The field resolution algorithm using a field path is:
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()):
122 <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
124 bt_packet_borrow_context_field_const().
126 <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
128 bt_event_borrow_common_context_field_const().
130 <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
132 bt_event_borrow_specific_context_field_const().
134 <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
136 bt_event_borrow_payload_field_const().
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()):
145 <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
147 Call bt_field_path_item_index_get_index() to get the item's
150 Depending on the current field's class's type (as
151 returned by bt_field_get_class_type()):
154 <dt>\bt_c_struct_fc</dt>
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
161 <dt>\bt_c_var_fc</dt>
163 Call bt_field_variant_borrow_selected_option_field_const()
164 with the current field to set the new current field.
169 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
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
178 <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
180 Call bt_field_option_borrow_field_const() with the current
181 field to set the new current field.
185 After applying this procedure, the current field is the linked
195 @typedef struct bt_field_path bt_field_path;
206 typedef enum bt_field_path_scope
{
211 BT_FIELD_PATH_SCOPE_PACKET_CONTEXT
= 0,
215 Event common context.
217 BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT
= 1,
221 Event specific context.
223 BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT
= 2,
229 BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD
= 3,
230 } bt_field_path_scope
;
234 Returns the root scope of the field path \bt_p{field_path}.
236 See the \ref api-tir-field-path-prop-root "root scope" property.
238 @param[in] field_path
239 Field path of which to get the root scope.
242 Root scope of \bt_p{field_path}.
244 @bt_pre_not_null{field_path}
246 extern bt_field_path_scope
bt_field_path_get_root_scope(
247 const bt_field_path
*field_path
);
251 Returns the number of items contained in the field path
254 See the \ref api-tir-field-path-prop-items "items" property.
256 @param[in] field_path
257 Field path of which to get the number of contained items.
260 Number of contained items in \bt_p{field_path}.
262 @bt_pre_not_null{field_path}
264 extern uint64_t bt_field_path_get_item_count(
265 const bt_field_path
*field_path
);
269 Borrows the item at index \bt_p{index} from the
270 field path \bt_p{field_path}.
272 See the \ref api-tir-field-path-prop-items "items" property.
274 @param[in] field_path
275 Field path from which to borrow the item at index \bt_p{index}.
277 Index of the item to borrow from \bt_p{field_path}.
281 \em Borrowed reference of the item of
282 \bt_p{field_path} at index \bt_p{index}.
284 The returned pointer remains valid as long as \bt_p{field_path}
288 @bt_pre_not_null{field_path}
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()).
293 @sa bt_field_path_get_item_count() —
294 Returns the number of items contained in a field path.
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
);
301 Increments the \ref api-fund-shared-object "reference count" of
302 the field path \bt_p{field_path}.
304 @param[in] field_path
306 Field path of which to increment the reference count.
311 @sa bt_field_path_put_ref() —
312 Decrements the reference count of a field path.
314 extern void bt_field_path_get_ref(const bt_field_path
*field_path
);
318 Decrements the \ref api-fund-shared-object "reference count" of
319 the field path \bt_p{field_path}.
321 @param[in] field_path
323 Field path of which to decrement the reference count.
328 @sa bt_field_path_get_ref() —
329 Increments the reference count of a field path.
331 extern void bt_field_path_put_ref(const bt_field_path
*field_path
);
335 Decrements the reference count of the field path
336 \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
340 Field path of which to decrement the reference count.
345 @bt_pre_assign_expr{_field_path}
347 #define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path) \
349 bt_field_path_put_ref(_field_path); \
350 (_field_path) = NULL; \
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.
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.
364 Destination expression.
375 @bt_pre_assign_expr{_dst}
376 @bt_pre_assign_expr{_src}
378 #define BT_FIELD_PATH_MOVE_REF(_dst, _src) \
380 bt_field_path_put_ref(_dst); \
388 @name Field path item
391 @typedef struct bt_field_path_item bt_field_path_item;
400 Field path item type enumerators.
402 typedef enum bt_field_path_item_type
{
405 Index of a \bt_struct_field member or selected \bt_var_field
408 BT_FIELD_PATH_ITEM_TYPE_INDEX
= 1 << 0,
412 Common field of an \bt_array_field.
414 BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT
= 1 << 1,
418 Current field of an \bt_opt_field.
420 BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT
= 1 << 2,
421 } bt_field_path_item_type
;
425 Returns the type enumerator of the field path item
428 See the \ref api-tir-field-path-prop-items "items" property.
431 Field path item of which to get the type enumerator
434 Type enumerator of \bt_p{item}.
436 @bt_pre_not_null{item}
438 extern bt_field_path_item_type
bt_field_path_item_get_type(
439 const bt_field_path_item
*item
);
443 Returns the index value of the index field path item
446 See the \ref api-tir-field-path-prop-items "items" property.
449 Index field path item of which to get the index value.
452 Index value of \bt_p{item}.
454 @bt_pre_not_null{item}
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).
460 extern uint64_t bt_field_path_item_index_get_index(
461 const bt_field_path_item
*item
);
471 #endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */