Map key API

Collaboration diagram for Map key API:

Data Structures
struct	lttng_map_key
	Map key (opaque type). More...
struct	lttng_map_key_set
	Immutable set of map keys (opaque type). More...

Enumerations
enum	lttng_map_key_set_status { LTTNG_MAP_KEY_SET_STATUS_OK , LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER , LTTNG_MAP_KEY_SET_STATUS_NOT_FOUND }
	Status code for map key set functions. More...
enum	lttng_map_key_status { LTTNG_MAP_KEY_STATUS_OK , LTTNG_MAP_KEY_STATUS_INVALID_PARAMETER }
	Status code for map key property accessors. More...
enum	lttng_map_key_type { LTTNG_MAP_KEY_TYPE_STRING }
	Type of the keys of a map. More...

Functions
enum lttng_map_key_status	lttng_map_key_get_index (const struct lttng_map_key *key, uint64_t *index)
	Sets *index to the entry index of key.
enum lttng_map_key_status	lttng_map_key_get_type (const struct lttng_map_key *key, enum lttng_map_key_type *type)
	Sets *type to the type of key.
void	lttng_map_key_set_destroy (struct lttng_map_key_set *set)
	Destroys the map key set set.
enum lttng_map_key_set_status	lttng_map_key_set_get_at_index (const struct lttng_map_key_set *set, uint64_t index, const struct lttng_map_key **key)
	Sets *key to the key at index index in set.
enum lttng_map_key_set_status	lttng_map_key_set_get_count (const struct lttng_map_key_set *set, uint64_t *count)
	Sets *count to the number of keys in set.
enum lttng_map_key_set_status	lttng_map_key_set_get_type (const struct lttng_map_key_set *set, enum lttng_map_key_type *type)
	Sets *type to the key type of set.
enum lttng_map_key_set_status	lttng_map_key_set_string_get_key_by_string (const struct lttng_map_key_set *set, const char *str, const struct lttng_map_key **key)
	Sets *key to the string map key in set whose string equals str.
enum lttng_map_key_status	lttng_map_key_string_get_string (const struct lttng_map_key *key, const char **str)
	Sets *str to the string of the string map key key.

Detailed Description

A map key identifies one entry of every map of a parent map channel: the mapping from key to entry index lives at the map channel level, and every map (per-partition view) which the channel manages exposes the same set of values at the same indices.

Each key has a type, which selects the type-specific accessors which apply to it. As of LTTng-tools 16.2, only the LTTNG_MAP_KEY_TYPE_STRING (string key) type exists.

LTTng adds a key to a map channel the first time the key template of an “increment map value” action which targets the channel expands to that effective key. The maximum key count of the channel caps the number of distinct keys which it can hold; when a map is full, LTTng silently drops any further new key.

Obtain the map keys of a map channel from the map channel itself.

Operations

The map key operations are:

Operation	Means
Iteration	Use lttng_map_key_set_get_count() and lttng_map_key_set_get_at_index().
Lookup	For a string key set (lttng_map_key_set_get_type() returns LTTNG_MAP_KEY_TYPE_STRING), use lttng_map_key_set_string_get_key_by_string().
Type access	For a single key lttng_map_key_get_type() For a key set lttng_map_key_set_get_type()
String access (string key)	Use lttng_map_key_string_get_string().
Index access	Use lttng_map_key_get_index() to obtain the entry index of a key. Use that index to address the corresponding entry in any map values object produced by the parent map channel.

The parent map channel owns its key set, which remains valid as long as the map channel exists.

Enumeration Type Documentation

lttng_map_key_set_status

enum lttng_map_key_set_status

Status code for map key set functions.

Enumerator
LTTNG_MAP_KEY_SET_STATUS_OK	Success.
LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.
LTTNG_MAP_KEY_SET_STATUS_NOT_FOUND	No matching map key found.

lttng_map_key_status

enum lttng_map_key_status

Status code for map key property accessors.

Enumerator
LTTNG_MAP_KEY_STATUS_OK	Success.
LTTNG_MAP_KEY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

lttng_map_key_type

enum lttng_map_key_type

Type of the keys of a map.

Enumerator
LTTNG_MAP_KEY_TYPE_STRING	String key.

Function Documentation

lttng_map_key_get_index()

enum lttng_map_key_status lttng_map_key_get_index ( const struct lttng_map_key *  key, uint64_t *  index  )

extern

Sets *index to the entry index of key.

Use *index to address the corresponding entry in any lttng_map_values produced by the map channel which owns key.

Parameters

[in]	key	Key of which to get the entry index.
[out]	index	On success, this function sets *index to the entry index of key.

Return values

LTTNG_MAP_KEY_STATUS_OK	Success.
LTTNG_MAP_KEY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• key is not NULL.
• index is not NULL.

lttng_map_key_get_type()

enum lttng_map_key_status lttng_map_key_get_type ( const struct lttng_map_key *  key, enum lttng_map_key_type *  type  )

extern

Sets *type to the type of key.

The type of key selects which type-specific accessors apply to it (for example, lttng_map_key_string_get_string() for the LTTNG_MAP_KEY_TYPE_STRING type).

Parameters

[in]	key	Key of which to get the type.
[out]	type	On success, this function sets *type to the type of key.

Return values

LTTNG_MAP_KEY_STATUS_OK	Success.
LTTNG_MAP_KEY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• key is not NULL.
• type is not NULL.

lttng_map_key_set_destroy()

void lttng_map_key_set_destroy ( struct lttng_map_key_set *  set )

extern

Destroys the map key set set.

Parameters

[in]

set

Map key set to destroy. May be NULL, in which case this function does nothing.

lttng_map_key_set_get_at_index()

enum lttng_map_key_set_status lttng_map_key_set_get_at_index ( const struct lttng_map_key_set *  set, uint64_t  index, const struct lttng_map_key **  key  )

extern

Sets *key to the key at index index in set.

Parameters

[in]	set	Key set of which to get a key.
[in]	index	Index of the key to get from set.
[out]	key	On success, this function sets *key to the key at index in set. set owns *key, which remains valid as long as set exists.

Return values

LTTNG_MAP_KEY_SET_STATUS_OK	Success.
LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• set is not NULL.
• index is less than the number of keys in set, as returned by lttng_map_key_set_get_count().
• key is not NULL.

See also

lttng_map_key_set_get_count() – Returns the number of keys in a map key set.

lttng_map_key_set_get_count()

enum lttng_map_key_set_status lttng_map_key_set_get_count ( const struct lttng_map_key_set *  set, uint64_t *  count  )

extern

Sets *count to the number of keys in set.

Parameters

[in]	set	Key set of which to get the number of keys.
[out]	count	On success, this function sets *count to the number of keys in set.

Return values

LTTNG_MAP_KEY_SET_STATUS_OK	Success.
LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• set is not NULL.
• count is not NULL.

See also

lttng_map_key_set_get_at_index() – Returns a key at a given index from a map key set.

lttng_map_key_set_get_type()

enum lttng_map_key_set_status lttng_map_key_set_get_type ( const struct lttng_map_key_set *  set, enum lttng_map_key_type *  type  )

extern

Sets *type to the key type of set.

All keys in set share this type, which selects which type-specific accessors apply (for example, lttng_map_key_set_string_get_key_by_string() for the LTTNG_MAP_KEY_TYPE_STRING type).

Parameters

[in]	set	Key set of which to get the key type.
[out]	type	On success, this function sets *type to the key type of set.

Return values

LTTNG_MAP_KEY_SET_STATUS_OK	Success.
LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• set is not NULL.
• type is not NULL.

lttng_map_key_set_string_get_key_by_string()

enum lttng_map_key_set_status lttng_map_key_set_string_get_key_by_string ( const struct lttng_map_key_set *  set, const char *  str, const struct lttng_map_key **  key  )

extern

Sets *key to the string map key in set whose string equals str.

Parameters

[in]	set	String key set in which to look up a key by string.
[in]	str	String of the key to find in set.
[out]	key	On success, this function sets *key to the key in set whose string equals str. set owns *key, which remains valid as long as set exists.

Return values

LTTNG_MAP_KEY_SET_STATUS_OK	Success.
LTTNG_MAP_KEY_SET_STATUS_NOT_FOUND	No key in set has the string str.
LTTNG_MAP_KEY_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition, including set not being a set of string keys.

Precondition

• set is not NULL.
• lttng_map_key_set_get_type() returns LTTNG_MAP_KEY_TYPE_STRING with set.
• str is not NULL.
• key is not NULL.

lttng_map_key_string_get_string()

enum lttng_map_key_status lttng_map_key_string_get_string ( const struct lttng_map_key *  key, const char **  str  )

extern

Sets *str to the string of the string map key key.

Parameters

[in]	key	String key of which to get the string.
[out]	str	On success, this function sets *str to the string of key. key owns *str, which remains valid as long as key exists.

Return values

LTTNG_MAP_KEY_STATUS_OK	Success.
LTTNG_MAP_KEY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

• key is not NULL.
• lttng_map_key_get_type() returns LTTNG_MAP_KEY_TYPE_STRING with key.
• str is not NULL.