Detailed Description

Path to a field.

A field path indicates how to reach a given field from a given root scope.

More specifically, a field path indicates how to reach:

The length field of a dynamic array field (with a length field).
The selector field of a option field (with a selector field).
The selector field of a variant field (with a selector field).

Note: The field path API is only available within a trace processing graph with the effective Message Interchange Protocol (MIP) version 0: use the similar field location API within a graph with the effective MIP version 1.

You can borrow the field path from the 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 event class or of a stream class. See Field classes with links to other field classes.

A field path is a trace IR metadata object.

A field path is a 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.

Properties

A field path has the following properties:

Root scope

Indicates from which structure field to start a lookup.

See Lookup algorithm to learn more.

Get the root scope of a field path with bt_field_path_get_root_scope().

Items

Each item in the item list of a field path indicates which action to take to follow the path to the linked field.

See 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 unique object: it belongs to the field path which contains it.

Lookup algorithm

The field resolution algorithm using a field path is:

Use the appropriate function to set a current field variable from the root scope (as returned by bt_field_path_get_root_scope()):

BT_FIELD_PATH_SCOPE_PACKET_CONTEXT

bt_packet_borrow_context_field_const().

BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT

bt_event_borrow_common_context_field_const().

BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT

bt_event_borrow_specific_context_field_const().

BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD

bt_event_borrow_payload_field_const().
For each field path item (use bt_field_path_get_item_count() and bt_field_path_borrow_item_by_index_const()), depending on the type of the item (as returned by bt_field_path_item_get_type()):

BT_FIELD_PATH_ITEM_TYPE_INDEX

Call bt_field_path_item_index_get_index() to get the index value of the item.

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

Structure field class

Call bt_field_structure_borrow_member_field_by_index_const() with the current field and with the index of the item to set the new current field.

Variant field class

Call bt_field_variant_borrow_selected_option_field_const() with the current field to set the new current field.

BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT

Call bt_field_array_borrow_element_field_by_index_const() with the index of the field eventually containing the field with a link (dynamic array field, option field, or variant field) and the current field to set the new current field.

BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT

Call bt_field_option_borrow_field_const() with the current field to set the new current field.

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

Field path
enum	bt_field_path_scope { BT_FIELD_PATH_SCOPE_PACKET_CONTEXT , BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT , BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT , BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD }
	Field path scopes. More...

typedef enum bt_field_path_scope	bt_field_path_scope
	Field path scopes.

typedef struct bt_field_path	bt_field_path
	Field path.

bt_field_path_scope	bt_field_path_get_root_scope (const bt_field_path *field_path)
	Returns the root scope of the field path field_path.

uint64_t	bt_field_path_get_item_count (const bt_field_path *field_path)
	Returns the number of items contained in the field path field_path.

const bt_field_path_item *	bt_field_path_borrow_item_by_index_const (const bt_field_path *field_path, uint64_t index)
	Borrows the item at index index from the field path field_path.

void	bt_field_path_get_ref (const bt_field_path *field_path)
	Increments the reference count of the field path field_path.

void	bt_field_path_put_ref (const bt_field_path *field_path)
	Decrements the reference count of the field path field_path.

#define	BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)
	Decrements the reference count of the field path _field_path, and then sets _field_path to `NULL`.

#define	BT_FIELD_PATH_MOVE_REF(_dst, _src)
	Decrements the reference count of the field path _dst, sets _dst to _src, and then sets _src to `NULL`.

Field path item
enum	bt_field_path_item_type { BT_FIELD_PATH_ITEM_TYPE_INDEX , BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT , BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT }
	Field path item type enumerators. More...

typedef enum bt_field_path_item_type	bt_field_path_item_type
	Field path item type enumerators.

typedef struct bt_field_path_item	bt_field_path_item
	Field path item.

bt_field_path_item_type	bt_field_path_item_get_type (const bt_field_path_item *item)
	Returns the type enumerator of the field path item item.

uint64_t	bt_field_path_item_index_get_index (const bt_field_path_item *item)
	Returns the index value of the index field path item item.

Enumeration Type Documentation

◆ bt_field_path_scope

enum bt_field_path_scope

Field path scopes.

Enumerator
BT_FIELD_PATH_SCOPE_PACKET_CONTEXT	Packet context.
BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT	Event common context.
BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT	Event specific context.
BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD	Event payload.

◆ bt_field_path_item_type

enum bt_field_path_item_type

Field path item type enumerators.

Enumerator
BT_FIELD_PATH_ITEM_TYPE_INDEX	Index of a structure field member or the field of a selected variant field option.
BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT	Common field of an array field.
BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT	Current field of an option field.

Macro Definition Documentation

◆ BT_FIELD_PATH_PUT_REF_AND_RESET

#define BT_FIELD_PATH_PUT_REF_AND_RESET ( _field_path )

Decrements the reference count of the field path _field_path, and then sets _field_path to NULL.

Parameters

_field_path

Field path of which to decrement the reference count.

Can contain NULL.

Precondition: _field_path is an assignable expression.

◆ BT_FIELD_PATH_MOVE_REF

#define BT_FIELD_PATH_MOVE_REF	(		_dst,
			_src )

Decrements the reference count of the field path _dst, sets _dst to _src, and then sets _src to NULL.

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

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

Function Documentation

◆ bt_field_path_get_root_scope()

bt_field_path_scope bt_field_path_get_root_scope ( const bt_field_path * field_path )

extern

Returns the root scope of the field path field_path.

See the root scope property.

Parameters

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

Returns: Root scope of field_path.

Precondition: field_path is not NULL.

◆ bt_field_path_get_item_count()

uint64_t bt_field_path_get_item_count ( const bt_field_path * field_path )

extern

Returns the number of items contained in the field path field_path.

See the items property.

Parameters

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

Returns: Number of contained items in field_path.

Precondition: field_path is not NULL.

◆ bt_field_path_borrow_item_by_index_const()

const bt_field_path_item * bt_field_path_borrow_item_by_index_const	(	const bt_field_path *	field_path,
		uint64_t	index )

extern

Borrows the item at index index from the field path field_path.

See the items property.

Parameters

[in]	field_path	Field path from which to borrow the item at index index.
[in]	index	Index of the item to borrow from field_path.

Returns

Borrowed reference of the item of field_path at index index.

The returned pointer remains valid as long as field_path exists.

Precondition: field_path is not NULL.; index is less than the number of items in field_path (as returned by bt_field_path_get_item_count()).

See also: bt_field_path_get_item_count() — Returns the number of items contained in a field path.

◆ bt_field_path_get_ref()

void bt_field_path_get_ref ( const bt_field_path * field_path )

extern

Increments the reference count of the field path field_path.

Parameters

[in]

field_path

Field path of which to increment the reference count.

Can be NULL.

See also: bt_field_path_put_ref() — Decrements the reference count of a field path.

◆ bt_field_path_put_ref()

void bt_field_path_put_ref ( const bt_field_path * field_path )

extern

Decrements the reference count of the field path field_path.

Parameters

[in]

field_path

Field path of which to decrement the reference count.

Can be NULL.

See also: bt_field_path_get_ref() — Increments the reference count of a field path.

◆ bt_field_path_item_get_type()

bt_field_path_item_type bt_field_path_item_get_type ( const bt_field_path_item * item )

extern

Returns the type enumerator of the field path item item.

See the items property.

Parameters

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

Returns: Type enumerator of item.

Precondition: item is not NULL.

◆ bt_field_path_item_index_get_index()

uint64_t bt_field_path_item_index_get_index ( const bt_field_path_item * item )

extern

Returns the index value of the index field path item item.

See the items property.

Parameters

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

Returns: Index value of item.

Precondition: item is not NULL.; item is an index field path item (bt_field_path_item_get_type() returns BT_FIELD_PATH_ITEM_TYPE_INDEX).