Field location

Detailed Description

Location of a field (available since Babeltrace 2.1).

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

Note

Unlike a field path, which is only available within a trace processing graph with the effective Message Interchange Protocol (MIP) version 0, a field location works with structure field member names, not with structure field member indexes.

This makes a field location more versatile than a field path, rendering possible, for example, multiple unsigned integer fields to act as candidates for the length field of a dynamic array field when they're part of the same variant field.

The field location API is only available within a trace processing graph with the effective MIP version 1.

A field location indicates how to reach:

• The length field of a dynamic BLOB field (instances with a linked length field).
• The length field of a dynamic array field (instances with a linked length field).
• The selector field of a option field (instances with a linked selector field).
• The selector field of a variant field (instances with a linked selector field).

You can borrow the field location from the classes of such fields with bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const(), bt_field_class_option_with_selector_field_borrow_selector_field_location_const(), and bt_field_class_variant_with_selector_field_borrow_selector_field_location_const(). See Field classes with links to other field classes.

A field location is a trace IR metadata object.

A field location is a shared object: get a new reference with bt_field_location_get_ref() and put an existing reference with bt_field_location_put_ref().

The type of a field location is bt_field_location.

Create a field location with bt_field_location_create().

Properties

A field location has the following properties:

Root scope

Indicates from which structure field to start a field location.

See Field location procedure to learn more.

Get the root scope of a field location with bt_field_location_get_root_scope().

Items

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

A field location item is a string (a structure field member name).

See Field location procedure to learn more.

Get the number of items in a field location with bt_field_location_get_item_count().

Get an item from a field location with bt_field_location_get_item_by_index().

A field location item always belongs to the field location which contains it.

Field location procedure

To locate a field from another field SRCFIELD using its field location FIELDLOC:

1. Let CURFIELD be, depending on the root scope of FIELDLOC (as returned by bt_field_location_get_root_scope()):

   BT_FIELD_LOCATION_SCOPE_PACKET_CONTEXT

   What bt_packet_borrow_context_field_const() returns for the current packet.

   BT_FIELD_LOCATION_SCOPE_EVENT_COMMON_CONTEXT

   What bt_event_borrow_common_context_field_const() returns for the current event.

   BT_FIELD_LOCATION_SCOPE_EVENT_SPECIFIC_CONTEXT

   What bt_event_borrow_specific_context_field_const() returns for the current event.

   BT_FIELD_LOCATION_SCOPE_EVENT_PAYLOAD

   What bt_event_borrow_payload_field_const() returns for the current event.

2. For each field location item NAME in FIELDLOC (use bt_field_location_get_item_count() and bt_field_location_get_item_by_index()):
   1. Let CURFIELD be the field of the structure field member named NAME within CURFIELD (as returned by bt_field_structure_borrow_member_field_by_name_const()).

   2. Depending on the class type of CURFIELD (as returned by bt_field_get_class_type()):

      BT_FIELD_CLASS_TYPE_BOOL

      BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER

      BT_FIELD_CLASS_TYPE_SIGNED_INTEGER

      BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION

      BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION

      End the field location procedure.

      BT_FIELD_CLASS_TYPE_STRUCTURE

      Continue.

      BT_FIELD_CLASS_TYPE_STATIC_ARRAY

      BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD

      BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD

      While the class type of CURFIELD is one of the three above (that is, while CURFIELD i an array field):

      • Set CURFIELD to the element field of CURFIELD (as returned by bt_field_array_borrow_element_field_by_index_const()) containing SRCFIELD.

      BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD

      BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD

      BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD

      BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD

      Set CURFIELD to the optional field of CURFIELD (as returned by bt_field_option_borrow_field_const()).

      BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD

      BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD

      BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD

      Set CURFIELD to the selected option field of CURFIELD (as returned by bt_field_variant_borrow_selected_option_field_const()).

After this procedure, CURFIELD is the located field.

Typedefs
typedef enum bt_field_location_scope	bt_field_location_scope
	Field location scope enumerators.

Enumerations
enum	bt_field_location_scope {   BT_FIELD_LOCATION_SCOPE_PACKET_CONTEXT ,   BT_FIELD_LOCATION_SCOPE_EVENT_COMMON_CONTEXT ,   BT_FIELD_LOCATION_SCOPE_EVENT_SPECIFIC_CONTEXT ,   BT_FIELD_LOCATION_SCOPE_EVENT_PAYLOAD }
	Field location scope enumerators. More...

Macros
#define	BT_FIELD_LOCATION_PUT_REF_AND_RESET(_field_location)
	Decrements the reference count of the field location _field_location, and then sets _field_location to NULL.
#define	BT_FIELD_LOCATION_MOVE_REF(_dst, _src)
	Decrements the reference count of the field location _dst, sets _dst to _src, and then sets _src to NULL.

Functions
bt_field_location *	bt_field_location_create (bt_trace_class *trace_class, bt_field_location_scope root_scope, const char *const *items, uint64_t item_count)
	Creates a field location from the trace class trace_class using the scope scope and the items items.
bt_field_location_scope	bt_field_location_get_root_scope (const bt_field_location *field_location)
	Returns the root scope of the field location field_location.
uint64_t	bt_field_location_get_item_count (const bt_field_location *field_location)
	Returns the number of items contained in the field location field_location.
const char *	bt_field_location_get_item_by_index (const bt_field_location *field_location, uint64_t index)
	Returns the item at index index from the field location field_location.
void	bt_field_location_get_ref (const bt_field_location *field_location)
	Increments the reference count of the field location field_location.
void	bt_field_location_put_ref (const bt_field_location *field_location)
	Decrements the reference count of the field location field_location.

Typedef Documentation

bt_field_location_scope

typedef enum bt_field_location_scope bt_field_location_scope

Field location scope enumerators.

Since

Babeltrace 2.1

Enumeration Type Documentation

bt_field_location_scope

enum bt_field_location_scope

Field location scope enumerators.

Since

Babeltrace 2.1

Enumerator
BT_FIELD_LOCATION_SCOPE_PACKET_CONTEXT	Context of the current packet.
BT_FIELD_LOCATION_SCOPE_EVENT_COMMON_CONTEXT	Common context of the current event.
BT_FIELD_LOCATION_SCOPE_EVENT_SPECIFIC_CONTEXT	Specific context of the current event.
BT_FIELD_LOCATION_SCOPE_EVENT_PAYLOAD	Payload of the current event.

Macro Definition Documentation

BT_FIELD_LOCATION_PUT_REF_AND_RESET

#define BT_FIELD_LOCATION_PUT_REF_AND_RESET

(

_field_location

)

Decrements the reference count of the field location _field_location, and then sets _field_location to NULL.

Parameters

_field_location

Field location of which to decrement the reference count. Can contain NULL.

Since

Babeltrace 2.1

Precondition

_field_location is an assignable expression.

BT_FIELD_LOCATION_MOVE_REF

#define BT_FIELD_LOCATION_MOVE_REF	(		_dst,
			_src )

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

This macro effectively moves a field location 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.

Since

Babeltrace 2.1

Precondition

_dst is an assignable expression.

_src is an assignable expression.

Function Documentation

bt_field_location_create()

bt_field_location * bt_field_location_create ( bt_trace_class * trace_class, bt_field_location_scope root_scope, const char *const * items, uint64_t item_count )

extern

Creates a field location from the trace class trace_class using the scope scope and the items items.

Parameters

[in]	trace_class	Trace class from which to create a field location.
[in]	root_scope	Root scope of the field location to create.
[in]	items	Items (copied) of the field location to create. item_count is the number of elements in items.
[in]	item_count	Number of elements in items.

Returns

New field location reference, or NULL on memory error.

Since

Babeltrace 2.1

Precondition

trace_class is not NULL.

trace_class was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version  1.

items is not NULL.

item_count ≥ 1.

bt_field_location_get_root_scope()

bt_field_location_scope bt_field_location_get_root_scope ( const bt_field_location * field_location )

extern

Returns the root scope of the field location field_location.

See the root scope property.

Parameters

[in]

field_location

Field location of which to get the root scope.

Returns

Root scope of field_location.

Since

Babeltrace 2.1

Precondition

field_location is not NULL.

bt_field_location_get_item_count()

uint64_t bt_field_location_get_item_count ( const bt_field_location * field_location )

extern

Returns the number of items contained in the field location field_location.

See the items property.

Parameters

[in]

field_location

Field location of which to get the number of contained items.

Returns

Number of contained items in field_location.

Since

Babeltrace 2.1

Precondition

field_location is not NULL.

See also

bt_field_location_get_item_by_index() — Returns an item by index from a field location.

bt_field_location_get_item_by_index()

const char * bt_field_location_get_item_by_index ( const bt_field_location * field_location, uint64_t index )

extern

Returns the item at index index from the field location field_location.

See the items property.

Parameters

[in]	field_location	Field location from which to borrow the item at index index.
[in]	index	Index of the item to borrow from field_location.

Returns

Item of field_location at index index.

The returned pointer remains valid as long as field_location exists.

Since

Babeltrace 2.1

Precondition

field_location is not NULL.

index is less than the number of items in field_location (as returned by bt_field_location_get_item_count()).

See also

bt_field_location_get_item_count() — Returns the number of items contained in a field location.

bt_field_location_get_ref()

void bt_field_location_get_ref ( const bt_field_location * field_location )

extern

Increments the reference count of the field location field_location.

Parameters

[in]

field_location

Field location of which to increment the reference count. Can be NULL.

Since

Babeltrace 2.1

See also

bt_field_location_put_ref() — Decrements the reference count of a field location.

bt_field_location_put_ref()

void bt_field_location_put_ref ( const bt_field_location * field_location )

extern

Decrements the reference count of the field location field_location.

Parameters

[in]

field_location

Field location of which to decrement the reference count. Can be NULL.

Since

Babeltrace 2.1

See also

bt_field_location_get_ref() — Increments the reference count of a field location.