[babeltrace.git] / include / babeltrace2 / trace-ir / field-path.h

#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
#define BABELTRACE2_TRACE_IR_FIELD_PATH_H

/*
 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <stdint.h>

#include <babeltrace2/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-tir-field-path Field path
@ingroup api-tir

@brief
    Path to a \bt_field.

A <strong><em>field path</em></strong> indicates how to reach a given
\bt_field from a given <em>root scope</em>.

More specifically, a field path indicates how to reach:

- The length field of a \bt_darray_field (with a length field).
- The selector field of a \bt_opt_field (with a selector field).
- The selector field of a \bt_var_field (with a selector field).

You can borrow the field path from the \ref api-tir-fc "classes" of such
fields with
bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
and
bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
Note that the field path properties of those field classes only becomes
available when the field class becomes part of an \bt_ev_cls or of a
\bt_stream_cls. See
\ref api-tir-fc-link "Field classes with links to other field classes".

A field path is a \ref api-tir "trace IR" metadata object.

A field path is a \ref api-fund-shared-object "shared object": get a
new reference with bt_field_path_get_ref() and put an existing
reference with bt_field_path_put_ref().

The type of a field path is #bt_field_path.

<h1>Properties</h1>

A field path has the following properties:

<dl>
  <dt>
    \anchor api-tir-field-path-prop-root
    Root scope
  </dt>
  <dd>
    Indicates from which \bt_struct_field to start a lookup.

    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
    learn more.

    Get a field path's root scope with bt_field_path_get_root_scope().
  </dd>

  <dt>
    \anchor api-tir-field-path-prop-items
    Items
  </dt>
  <dd>
    Each item in a field path's item list indicates which action to take
    to follow the path to the linked \bt_field.

    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
    learn more.

    Get the number of items in a field path with
    bt_field_path_get_item_count().

    Borrow an item from a field path with
    bt_field_path_borrow_item_by_index_const(). This function
    returns the #bt_field_path_item type.

    A field path item is a \ref api-fund-unique-object "unique object":
    it belongs to the field path which contains it.
  </dd>
</dl>

<h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>

The field resolution algorithm using a field path is:

-# Use the appropriate function to set a <em>current field</em> variable
   from the root scope (as returned by bt_field_path_get_root_scope()):

   <dl>
     <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
     <dd>
       bt_packet_borrow_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
     <dd>
       bt_event_borrow_common_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
     <dd>
       bt_event_borrow_specific_context_field_const().
     </dd>
     <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
     <dd>
       bt_event_borrow_payload_field_const().
     </dd>
   </dl>

-# For each field path item (use bt_field_path_get_item_count()
   and bt_field_path_borrow_item_by_index_const()), depending on
   the item's type (as returned by bt_field_path_item_get_type()):

   <dl>
     <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
     <dd>
       Call bt_field_path_item_index_get_index() to get the item's
       index value.

       Depending on the current field's class's type (as
       returned by bt_field_get_class_type()):

       <dl>
         <dt>\bt_c_struct_fc</dt>
         <dd>
           Call bt_field_structure_borrow_member_field_by_index_const()
           with the current field and with the item's index to set the
           new current field.
         </dd>

         <dt>\bt_c_var_fc</dt>
         <dd>
           Call bt_field_variant_borrow_selected_option_field_const()
           with the current field to set the new current field.
         </dd>
       </dl>
     </dd>

     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
     <dd>
       Call bt_field_array_borrow_element_field_by_index_const()
       with the index of the field eventually containing the
       field with a link (\bt_darray_field, \bt_opt_field, or
       \bt_var_field) and the current field to set the new current
       field.
     </dd>

     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
     <dd>
       Call bt_field_option_borrow_field_const() with the current
       field to set the new current field.
     </dd>
   </dl>

After applying this procedure, the current field is the linked
field.
*/

/*! @{ */

/*!
@name Field path
@{

@typedef struct bt_field_path bt_field_path;

@brief
    Field path.

*/

/*!
@brief
    Field path scopes.
*/
typedef enum bt_field_path_scope {
	/*!
	@brief
	    Packet context.
	*/
	BT_FIELD_PATH_SCOPE_PACKET_CONTEXT		= 0,

	/*!
	@brief
	    Event common context.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT	= 1,

	/*!
	@brief
	    Event specific context.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT	= 2,

	/*!
	@brief
	    Event payload.
	*/
	BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD		= 3,
} bt_field_path_scope;

/*!
@brief
    Returns the root scope of the field path \bt_p{field_path}.

See the \ref api-tir-field-path-prop-root "root scope" property.

@param[in] field_path
    Field path of which to get the root scope.

@returns
    Root scope of \bt_p{field_path}.

@bt_pre_not_null{field_path}
*/
extern bt_field_path_scope bt_field_path_get_root_scope(
		const bt_field_path *field_path);

/*!
@brief
    Returns the number of items contained in the field path
    \bt_p{field_path}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] field_path
    Field path of which to get the number of contained items.

@returns
    Number of contained items in \bt_p{field_path}.

@bt_pre_not_null{field_path}
*/
extern uint64_t bt_field_path_get_item_count(
		const bt_field_path *field_path);

/*!
@brief
    Borrows the item at index \bt_p{index} from the
    field path \bt_p{field_path}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] field_path
    Field path from which to borrow the item at index \bt_p{index}.
@param[in] index
    Index of the item to borrow from \bt_p{field_path}.

@returns
    @parblock
    \em Borrowed reference of the item of
    \bt_p{field_path} at index \bt_p{index}.

    The returned pointer remains valid as long as \bt_p{field_path}
    exists.
    @endparblock

@bt_pre_not_null{field_path}
@pre
    \bt_p{index} is less than the number of items in
    \bt_p{field_path} (as returned by bt_field_path_get_item_count()).

@sa bt_field_path_get_item_count() &mdash;
    Returns the number of items contained in a field path.
*/
extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
		const bt_field_path *field_path, uint64_t index);

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the field path \bt_p{field_path}.

@param[in] field_path
    @parblock
    Field path of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_field_path_put_ref() &mdash;
    Decrements the reference count of a field path.
*/
extern void bt_field_path_get_ref(const bt_field_path *field_path);

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the field path \bt_p{field_path}.

@param[in] field_path
    @parblock
    Field path of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_field_path_get_ref() &mdash;
    Increments the reference count of a field path.
*/
extern void bt_field_path_put_ref(const bt_field_path *field_path);

/*!
@brief
    Decrements the reference count of the field path
    \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.

@param _field_path
    @parblock
    Field path of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_field_path}
*/
#define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)	\
	do {						\
		bt_field_path_put_ref(_field_path);	\
		(_field_path) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the field path \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves a field path reference from the expression
\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
\bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_FIELD_PATH_MOVE_REF(_dst, _src)	\
	do {					\
		bt_field_path_put_ref(_dst);	\
		(_dst) = (_src);		\
		(_src) = NULL;			\
	} while (0)

/*! @} */

/*!
@name Field path item
@{

@typedef struct bt_field_path_item bt_field_path_item;

@brief
    Field path item.

*/

/*!
@brief
    Field path item type enumerators.
*/
typedef enum bt_field_path_item_type {
	/*!
	@brief
	    Index of a \bt_struct_field member or selected \bt_var_field
	    option's field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_INDEX				= 1 << 0,

	/*!
	@brief
	    Common field of an \bt_array_field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT		= 1 << 1,

	/*!
	@brief
	    Current field of an \bt_opt_field.
	*/
	BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT		= 1 << 2,
} bt_field_path_item_type;

/*!
@brief
    Returns the type enumerator of the field path item
    \bt_p{item}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] item
    Field path item of which to get the type enumerator

@returns
    Type enumerator of \bt_p{item}.

@bt_pre_not_null{item}
*/
extern bt_field_path_item_type bt_field_path_item_get_type(
		const bt_field_path_item *item);

/*!
@brief
    Returns the index value of the index field path item
    \bt_p{item}.

See the \ref api-tir-field-path-prop-items "items" property.

@param[in] item
    Index field path item of which to get the index value.

@returns
    Index value of \bt_p{item}.

@bt_pre_not_null{item}
@pre
    \bt_p{item} is an index field path item
    (bt_field_path_item_get_type() returns
    #BT_FIELD_PATH_ITEM_TYPE_INDEX).
*/
extern uint64_t bt_field_path_item_index_get_index(
		const bt_field_path_item *item);

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */
Commit	Line	Data
43c59509 PP	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() —
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() —
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() —
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 */