Collaboration diagram for Map value API:

Data Structures
struct	lttng_map_values
	Per-partition map values object (opaque type). More...

struct	lttng_map_values_set
	Set of per-partition map values objects (opaque type). More...

Enumerations
enum	lttng_map_value_type { LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 , LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64 , LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX }
	Type of the values of a map. More...

enum	lttng_map_values_set_status { LTTNG_MAP_VALUES_SET_STATUS_OK , LTTNG_MAP_VALUES_SET_STATUS_INVALID_PARAMETER }
	Status code for map values object set functions. More...

enum	lttng_map_values_status { LTTNG_MAP_VALUES_STATUS_OK , LTTNG_MAP_VALUES_STATUS_INVALID_PARAMETER }
	Status code for map values object functions. More...

Functions
enum lttng_map_values_status	lttng_map_values_get_partition_id (const struct lttng_map_values values, unsigned int partition_id)
	Sets `*partition_id` to the partition ID which `values` corresponds to within the partitioning of its parent group.

void	lttng_map_values_set_destroy (struct lttng_map_values_set *set)
	Destroys the map values object set `set`.

enum lttng_map_values_set_status	lttng_map_values_set_get_at_index (const struct lttng_map_values_set set, uint64_t index, const struct lttng_map_values *values)
	Sets `*values` to the map values object at index `index` in `set`.

enum lttng_map_values_set_status	lttng_map_values_set_get_count (const struct lttng_map_values_set set, uint64_t count)
	Sets `*count` to the number of map values objects in `set`.

enum lttng_map_values_status	lttng_map_values_signed_int_get_value_at_index (const struct lttng_map_values values, uint64_t index, int64_t value)
	Sets `*value` to the value of the entry at `index` in the signed integer map values object `values`.

enum lttng_map_values_status	lttng_map_values_signed_int_has_overflow_at_index (const struct lttng_map_values values, uint64_t index, bool has_overflow)
	Sets `*has_overflow` to whether or not the entry at `index` in the signed integer map values object `values` has had at least one arithmetic update wrap around (modular arithmetic) because the result could not be represented in the effective value type of the map group.

Detailed Description

A map value is the integer (as of LTTng-tools 16.2) associated with one (map, key) pair of a map channel.

The storage width and signedness of a map value follow the value type of the parent map channel.

Obtain the map values of a map group by sampling the map group.

Operations

The map value operations are:

Operation	Means
Iteration over partitions	Use lttng_map_values_set_get_count() and lttng_map_values_set_get_at_index() to walk through the per-partition values objects of a values set.
Value access (signed integer values)	As of LTTng-tools 16.2, the only available value types are signed integers (LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32, LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64, and LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX). Therefore: Read the value of an entry lttng_map_values_signed_int_get_value_at_index(). Check whether at least one arithmetic update of an entry wrapped around (modular arithmetic) because the result couldn't be represented with the effective value type of the map group lttng_map_values_signed_int_has_overflow_at_index(). Use the entry index of a specific key to address the corresponding entry.
Reset	Resetting the values of all the maps of all the map channels of a recording session to 0, without removing the keys themselves, is part of recording session clearing. See also `lttng-clear(1)`
Destruction	Destroy a values set obtained from lttng_map_group_get_values() with lttng_map_values_set_destroy().

See also: lttng-show-maps(1)

Enumeration Type Documentation

◆ lttng_map_value_type

enum lttng_map_value_type

Type of the values of a map.

Enumerator

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32

32-bit signed integer.

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64

64-bit signed integer.

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX

Signed integer with the native width of the session daemon process.

With this value type, the map channel uses 32-bit values when the session daemon runs as a 32-bit process, and 64-bit values when it runs as a 64-bit process.

Attention: As of LTTng stable-2.16, a map channel with this value type is not accessible from instrumented 32-bit applications when the session daemon runs as a 64-bit process. If you need the map channel to be accessible from both instrumented 32-bit and 64-bit applications, use LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 instead.

◆ lttng_map_values_set_status

enum lttng_map_values_set_status

Status code for map values object set functions.

Enumerator
LTTNG_MAP_VALUES_SET_STATUS_OK	Success.
LTTNG_MAP_VALUES_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

◆ lttng_map_values_status

enum lttng_map_values_status

Status code for map values object functions.

Enumerator
LTTNG_MAP_VALUES_STATUS_OK	Success.
LTTNG_MAP_VALUES_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Function Documentation

◆ lttng_map_values_get_partition_id()

enum lttng_map_values_status lttng_map_values_get_partition_id	(	const struct lttng_map_values *	values,
		unsigned int *	partition_id
	)

extern

Sets *partition_id to the partition ID which values corresponds to within the partitioning of its parent group.

This function does not apply to a map values object produced by a shared map group (a map group of type LTTNG_MAP_GROUP_TYPE_SHARED), which has no per-partition decomposition.

Parameters

[in]	values	Map values object of which to get the partition ID.
[out]	partition_id	On success, this function sets `*partition_id` to the partition ID of `values`.

Return values

LTTNG_MAP_VALUES_STATUS_OK	Success.
LTTNG_MAP_VALUES_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

values is not NULL.
The type of the map group which produced values is not LTTNG_MAP_GROUP_TYPE_SHARED.
partition_id is not NULL.

◆ lttng_map_values_set_destroy()

void lttng_map_values_set_destroy ( struct lttng_map_values_set * set )

extern

Destroys the map values object set set.

Parameters

[in]

set

Map values set to destroy.

May be NULL, in which case this function does nothing.

◆ lttng_map_values_set_get_at_index()

enum lttng_map_values_set_status lttng_map_values_set_get_at_index	(	const struct lttng_map_values_set *	set,
		uint64_t	index,
		const struct lttng_map_values **	values
	)

extern

Sets *values to the map values object at index index in set.

Parameters

[in] set Map values set of which to get a map values object.

[in] index Index of the map values object to get from set.

[out]

values

On success, this function sets *values to the map values object at index in set.

set owns *values, which remains valid as long as set exists.

Return values

LTTNG_MAP_VALUES_SET_STATUS_OK	Success.
LTTNG_MAP_VALUES_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

set is not NULL.
index is less than the number of map values objects in set, as returned by lttng_map_values_set_get_count().
values is not NULL.

See also: lttng_map_values_set_get_count() – Returns the number of map values objects in a map values set.

◆ lttng_map_values_set_get_count()

enum lttng_map_values_set_status lttng_map_values_set_get_count	(	const struct lttng_map_values_set *	set,
		uint64_t *	count
	)

extern

Sets *count to the number of map values objects in set.

Parameters

[in]	set	Map values set of which to get the number of map values objects.
[out]	count	On success, this function sets `*count` to the number of map values objects in `set`.

Return values

LTTNG_MAP_VALUES_SET_STATUS_OK	Success.
LTTNG_MAP_VALUES_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

set is not NULL.
count is not NULL.

See also: lttng_map_values_set_get_at_index() – Returns a map values object at a given index from a map values set.

◆ lttng_map_values_signed_int_get_value_at_index()

enum lttng_map_values_status lttng_map_values_signed_int_get_value_at_index	(	const struct lttng_map_values *	values,
		uint64_t	index,
		int64_t *	value
	)

extern

Sets *value to the value of the entry at index in the signed integer map values object values.

The entry index space is defined by the parent map channel, regardless of the channel's key type: use the channel API to translate a key (for example a string) to its corresponding index.

Parameters

[in]	values	Signed integer map values object of which to get an entry value.
[in]	index	Index of the entry of which to get the value from `values`.
[out]	value	On success, this function sets `*value` to the value of the entry at `index` in `values`.

Return values

LTTNG_MAP_VALUES_STATUS_OK	Success.
LTTNG_MAP_VALUES_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

values is not NULL.
lttng_map_channel_get_value_type() returns LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32, LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64, or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX with the map channel from which values was obtained.
index is the index of a valid key of the map channel from which values was obtained (see lttng_map_channel_get_keys()).
value is not NULL.

See also: lttng_map_values_signed_int_has_overflow_at_index() – Returns whether an entry of a signed integer map values object has overflowed.

◆ lttng_map_values_signed_int_has_overflow_at_index()

enum lttng_map_values_status lttng_map_values_signed_int_has_overflow_at_index	(	const struct lttng_map_values *	values,
		uint64_t	index,
		bool *	has_overflow
	)

extern

Sets *has_overflow to whether or not the entry at index in the signed integer map values object values has had at least one arithmetic update wrap around (modular arithmetic) because the result could not be represented in the effective value type of the map group.

Parameters

[in]	values	Signed integer map values object of which to get an entry overflow indicator.
[in]	index	Index of the entry of which to get the overflow indicator from `values`.
[out]	has_overflow	On success, this function sets `*has_overflow` to whether or not the entry at `index` in `values` has overflowed.

Return values

LTTNG_MAP_VALUES_STATUS_OK	Success.
LTTNG_MAP_VALUES_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

values is not NULL.
lttng_map_channel_get_value_type() returns LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32, LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64, or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX with the map channel from which values was obtained.
index is the index of a valid key of the map channel from which values was obtained (see lttng_map_channel_get_keys()).
value is not NULL.

See also: lttng_map_values_signed_int_get_value_at_index() – Returns the value of an entry of a signed integer map values object.

Data Structures

Enumerations

Functions

Detailed Description

Operations

Enumeration Type Documentation

◆ lttng_map_value_type

◆ lttng_map_values_set_status

◆ lttng_map_values_status

Function Documentation

◆ lttng_map_values_get_partition_id()

◆ lttng_map_values_set_destroy()

◆ lttng_map_values_set_get_at_index()

◆ lttng_map_values_set_get_count()

◆ lttng_map_values_signed_int_get_value_at_index()

◆ lttng_map_values_signed_int_has_overflow_at_index()