Trigger action list API

Collaboration diagram for Trigger action list API:

Functions
enum lttng_action_status	lttng_action_list_add_action (struct lttng_action *action_list, struct lttng_action *action)
	Appends the trigger action action to the action list action_list.
struct lttng_action *	lttng_action_list_create (void)
	Creates an empty trigger action list.
const struct lttng_action *	lttng_action_list_get_at_index (const struct lttng_action *action_list, unsigned int index)
	Returns the trigger action of the trigger action list action_list at the index index.
enum lttng_action_status	lttng_action_list_get_count (const struct lttng_action *action_list, unsigned int *count)
	Sets *count to the number of trigger actions contained in the action list action_list.

Detailed Description

A trigger action list is an ordered sequence of trigger actions.

A trigger action list is an action itself: it has the type LTTNG_ACTION_TYPE_LIST.

When a trigger having an action list as its action fires, LTTng attempts to execute its contained actions, in order. Whether or not LTTng executes a contained action depends on its rate policy. An action list doesn't have a rate policy itself.

Note

An “increment map value” action may execute out of order: when an action list contains at least one “increment map value” action, LTTng doesn't guarantee the execution order of the “increment map value” action(s) relative to all the actions of the list, including other “increment map value” actions. In other words, the order of the action list only holds amongst its non-“increment map value” actions.

Create a trigger action list with lttng_action_list_create().

Add a trigger action to an action list with lttng_action_list_add_action().

Get a trigger action from an action list with lttng_action_list_get_count() and lttng_action_list_get_at_index().

Function Documentation

lttng_action_list_add_action()

enum lttng_action_status lttng_action_list_add_action ( struct lttng_action *  action_list, struct lttng_action *  action  )

extern

Appends the trigger action action to the action list action_list.

Parameters

[in]	action_list	Trigger action list to which to add the action action.
[in]	action	Trigger action to add to action_list (not moved).

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action_list is not NULL.
• action_list has the type LTTNG_ACTION_TYPE_LIST.
• action is not NULL.
• action doesn't recursively contain action_list (no reference cycle).

lttng_action_list_create()

struct lttng_action * lttng_action_list_create ( void  )

extern

Creates an empty trigger action list.

Returns

Trigger action with the type LTTNG_ACTION_TYPE_LIST on success, or NULL on error.

Destroy the returned trigger action with lttng_action_destroy().

lttng_action_list_get_at_index()

const struct lttng_action * lttng_action_list_get_at_index ( const struct lttng_action *  action_list, unsigned int  index  )

extern

Returns the trigger action of the trigger action list action_list at the index index.

Parameters

[in]	action_list	Trigger action list of which to get the action at the index index.
[in]	index	Index of the trigger action to get from action_list.

Returns

Trigger action of action_list at the index index, or NULL on error.

action_list owns the returned trigger action.

The returned trigger action remains valid as long as action_list exists.

Precondition

• action_list is not NULL.
• action_list has the type LTTNG_ACTION_TYPE_LIST.
• index is less than the number of trigger actions (as returned by lttng_action_list_get_count()) of action_list.

See also

lttng_action_list_get_count() – Get the number of trigger actions of an action list.

lttng_action_list_get_count()

enum lttng_action_status lttng_action_list_get_count ( const struct lttng_action *  action_list, unsigned int *  count  )

extern

Sets *count to the number of trigger actions contained in the action list action_list.

Parameters

[in]	action_list	Trigger action list of which to get the number of contained actions.
[out]	count	On success, this function sets *count to the number of trigger actions in action_list.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action_list is not NULL.
• action_list has the type LTTNG_ACTION_TYPE_LIST.
• count is not NULL.

See also

lttng_action_list_get_at_index() – Get a trigger action from an action list by index.