Collaboration diagram for Notification channel API:

Data Structures
struct	lttng_endpoint
	LTTng endpoint (opaque type). More...

struct	lttng_notification
	Notification (opaque type). More...

struct	lttng_notification_channel
	Notification channel (opaque type). More...

Enumerations
enum	lttng_notification_channel_status { LTTNG_NOTIFICATION_CHANNEL_STATUS_OK , LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED , LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED , LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR , LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED , LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED , LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION , LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID , LTTNG_NOTIFICATION_CHANNEL_STATUS_UNSUPPORTED_VERSION }
	Return type of notification channel API functions. More...

Functions
struct lttng_notification_channel *	lttng_notification_channel_create (struct lttng_endpoint *endpoint)
	Creates a notification channel, connecting to the endpoint `endpoint`, without any subscription.

void	lttng_notification_channel_destroy (struct lttng_notification_channel *channel)
	Destroys the notification channel `channel`.

enum lttng_notification_channel_status	lttng_notification_channel_get_next_notification (struct lttng_notification_channel channel, struct lttng_notification *notification)
	Blocks the current thread until the next notification is available from the notification channel `channel` and sets `*notification` accordingly.

enum lttng_notification_channel_status	lttng_notification_channel_has_pending_notification (struct lttng_notification_channel channel, bool notification_avail)
	Sets `*notification_avail` to whether or not the notification channel `channel` has an available notification to get.

enum lttng_notification_channel_status	lttng_notification_channel_subscribe (struct lttng_notification_channel channel, const struct lttng_condition condition)
	Makes the notification channel `channel` subscribe to the notifications which LTTng sends when a trigger having the condition `condition` fires.

enum lttng_notification_channel_status	lttng_notification_channel_unsubscribe (struct lttng_notification_channel channel, const struct lttng_condition condition)
	Makes the notification channel `channel` unsubscribe from the notifications which LTTng sends when a trigger having the condition `condition` fires.

void	lttng_notification_destroy (struct lttng_notification *notification)
	Destroys the notification `notification`.

const struct lttng_condition *	lttng_notification_get_condition (struct lttng_notification *notification)
	Returns the condition which caused a trigger to send the notification `notification`.

const struct lttng_evaluation *	lttng_notification_get_evaluation (struct lttng_notification *notification)
	Returns the evaluation of the condition which caused a trigger to send the notification `notification`.

const struct lttng_trigger *	lttng_notification_get_trigger (struct lttng_notification *notification)
	Returns the trigger which fired to make LTTng send the notification `notification`.

Variables
struct lttng_endpoint *	lttng_session_daemon_notification_endpoint
	LTTng session daemon notification endpoint.

Detailed Description

A notification channel is a special connection to an LTTng session daemon with which you subscribe to notifications which LTTng sends when specific trigger conditions are satisfied.

LTTng sends a notification to subscribed notification channels when it executes a “notify” trigger action.

To use a notification channel:

Create a notification channel with lttng_notification_channel_create().

This call establishes a dedicated, persistent connection with an LTTng session daemon.
Call lttng_notification_channel_subscribe() one or more times to subscribe the notifications which LTTng sends when triggers with specific conditions fire.
Call lttng_notification_channel_get_next_notification() to block the current thread until the channel receives a new notification. Repeat as needed.

You may also call the non-blocking lttng_notification_channel_has_pending_notification() function to check whether or not lttng_notification_channel_get_next_notification() would return immediately.

With a notification object in hand, you may get:
- The trigger which fired to send this notification with lttng_notification_get_trigger().
- The satisfied trigger condition with lttng_notification_get_condition().
- The evaluation of the satisfied trigger condition with lttng_notification_get_evaluation().
  
  This object contains values which LTTng captured when the trigger fired.
When you're done with the notification, destroy it with lttng_notification_destroy().
When you're done with the notification channel, destroy it with lttng_notification_channel_destroy().

During the lifetime of the notification channel, you may call lttng_notification_channel_subscribe() and lttng_notification_channel_unsubscribe() as you will to modify its subscriptions.

Note: If your goal is to capture a large amount of tracing data with a trigger having an “event rule matches” condition and a “notify” action, then prefer creating and using a recording session instead.

Enumeration Type Documentation

◆ lttng_notification_channel_status

enum lttng_notification_channel_status

Return type of notification channel API functions.

Enumerator
LTTNG_NOTIFICATION_CHANNEL_STATUS_OK	Success.
LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED	Notification was dropped/discarded.
LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED	Woken up by a signal.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR	Error.
LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED	Connection closed.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED	Already subscribed.
LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION	Unknown trigger condition.
LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID	Unsatisfied precondition.

Function Documentation

◆ lttng_notification_channel_create()

struct lttng_notification_channel * lttng_notification_channel_create ( struct lttng_endpoint * endpoint )

extern

Creates a notification channel, connecting to the endpoint endpoint, without any subscription.

Parameters

[in] endpoint Endpoint to connect to: must be exactly lttng_session_daemon_notification_endpoint.

Returns

Notification channel on success, or NULL on error.

Destroy the returned notification channel with lttng_notification_channel_destroy().

Precondition

- liblttng-ctl can connect to a session daemon.
endpoint is lttng_session_daemon_notification_endpoint.

◆ lttng_notification_channel_destroy()

void lttng_notification_channel_destroy ( struct lttng_notification_channel * channel )

extern

Destroys the notification channel channel.

Parameters

[in]

channel

Notification channel to destroy.

May be NULL.

◆ lttng_notification_channel_get_next_notification()

enum lttng_notification_channel_status lttng_notification_channel_get_next_notification	(	struct lttng_notification_channel *	channel,
		struct lttng_notification **	notification
	)

extern

Blocks the current thread until the next notification is available from the notification channel channel and sets *notification accordingly.

To avoid blocking when calling this function, check if a notification is available first with lttng_notification_channel_has_pending_notification().

Parameters

[in] channel Notification channel from which to get the next notification.

[out]

notification

On success, this function sets *notification to the next notification of channel.

Destroy the returned notification with lttng_notification_destroy().

Return values

LTTNG_NOTIFICATION_CHANNEL_STATUS_OK	Success.
LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED	One or more notifications were dropped because the client couldn't keep up.
LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED	The blocking wait was interrupted by a signal.
LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID	Unsatisfied precondition.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR	Other error.

Precondition

channel is not NULL.
notification is not NULL.

See also: lttng_notification_channel_has_pending_notification() – Check whether or not a notification channel has an available notification.

◆ lttng_notification_channel_has_pending_notification()

enum lttng_notification_channel_status lttng_notification_channel_has_pending_notification	(	struct lttng_notification_channel *	channel,
		bool *	notification_avail
	)

extern

Sets *notification_avail to whether or not the notification channel channel has an available notification to get.

Unlike lttng_notification_channel_get_next_notification(), this function doesn't block the current thread.

Parameters

[in] channel Notification channel to check.

[out]

notification_avail

On success, this function sets *notification_avail to one of:

true

channel has an available notification.

Get the available notification with lttng_notification_channel_get_next_notification(), which won't block the current thread.

false

channel has no available notification.

Return values

LTTNG_NOTIFICATION_CHANNEL_STATUS_OK	Success.
LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED	The connection of the notification channel is closed.
LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID	Unsatisfied precondition.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR	Other error.

Precondition

channel is not NULL.
notification_avail is not NULL.

See also: lttng_notification_channel_get_next_notification() – Get the next available notification from a notification channel.

◆ lttng_notification_channel_subscribe()

enum lttng_notification_channel_status lttng_notification_channel_subscribe	(	struct lttng_notification_channel *	channel,
		const struct lttng_condition *	condition
	)

extern

Makes the notification channel channel subscribe to the notifications which LTTng sends when a trigger having the condition condition fires.

When a trigger having a condition exactly equal to condition and a “notify” action fires, LTTng sends a notification to the notification channel channel.

Reverse this subscription and stop receiving notifications with lttng_notification_channel_unsubscribe().

You may only call this function once with a given trigger condition without first calling lttng_notification_channel_unsubscribe() with it.

Parameters

[in]	channel	Notification channel to which to add a subscription.
[in]	condition	Trigger condition which must be satisfied for LTTng to send the notifications to subscribe to (not moved).

Return values

LTTNG_NOTIFICATION_CHANNEL_STATUS_OK	Success.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED	This function was already called with `channel` and `condition` without first calling lttng_notification_channel_unsubscribe() (double subscription).
LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID	Unsatisfied precondition.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR	Other error.

Precondition

channel is not NULL.
condition is not NULL.

See also: lttng_notification_channel_unsubscribe() – Make a notification channel unsubscribe from the notifications which LTTng sends when a trigger having some condition fires.

◆ lttng_notification_channel_unsubscribe()

enum lttng_notification_channel_status lttng_notification_channel_unsubscribe	(	struct lttng_notification_channel *	channel,
		const struct lttng_condition *	condition
	)

extern

Makes the notification channel channel unsubscribe from the notifications which LTTng sends when a trigger having the condition condition fires.

You may only call this function if you already called lttng_notification_channel_subscribe() with the same parameters.

Parameters

[in]	channel	Notification channel from which to remove a subscription.
[in]	condition	Trigger condition which must be satisfied for LTTng to send the notifications to unsubscribe from (not moved).

Return values

LTTNG_NOTIFICATION_CHANNEL_STATUS_OK	Success.
LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION	lttng_notification_channel_subscribe() wasn't called with the same parameters first (no subscription).
LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID	Unsatisfied precondition.
LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR	Other error.

Precondition

channel is not NULL.
condition is not NULL.

See also: lttng_notification_channel_subscribe() – Make a notification channel subscribe to the notifications which LTTng sends when a trigger having some condition fires.

◆ lttng_notification_destroy()

void lttng_notification_destroy ( struct lttng_notification * notification )

extern

Destroys the notification notification.

Parameters

[in]

notification

Notification to destroy.

May be NULL.

◆ lttng_notification_get_condition()

const struct lttng_condition * lttng_notification_get_condition ( struct lttng_notification * notification )

extern

Returns the condition which caused a trigger to send the notification notification.

Parameters

[in] notification Notification of which to get the satisfied trigger condition.

Returns

Satisfied trigger condition which caused a trigger to send notification, or NULL on error.

notification owns the returned trigger condition.

The returned trigger condition remains valid as long as notification exists.

Precondition

notification is not NULL.

◆ lttng_notification_get_evaluation()

const struct lttng_evaluation * lttng_notification_get_evaluation ( struct lttng_notification * notification )

extern

Returns the evaluation of the condition which caused a trigger to send the notification notification.

A trigger condition evaluation contains values which LTTng captured when the trigger fired.

Parameters

[in] notification Notification of which to get the evaluation of the satisfied trigger condition.

Returns

Evaluation of the satisfied trigger condition which caused a trigger to send notification, or NULL on error.

notification owns the returned trigger condition evaluation.

The returned trigger condition evaluation remains valid as long as notification exists.

Precondition

notification is not NULL.

◆ lttng_notification_get_trigger()

const struct lttng_trigger * lttng_notification_get_trigger ( struct lttng_notification * notification )

extern

Returns the trigger which fired to make LTTng send the notification notification.

Parameters

[in] notification Notification of which to get the firing trigger.

Returns

Trigger which fired, making LTTng send notification, or NULL on error.

notification owns the returned trigger.

The returned trigger remains valid as long as notification exists.

Precondition

notification is not NULL.

Variable Documentation

◆ lttng_session_daemon_notification_endpoint

struct lttng_endpoint* lttng_session_daemon_notification_endpoint

extern

LTTng session daemon notification endpoint.

This endpoint follows the typical session daemon connection procedure.

The purpose of this endpoint is to create a notification channel with lttng_notification_channel_create().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ lttng_notification_channel_status

Function Documentation

◆ lttng_notification_channel_create()

◆ lttng_notification_channel_destroy()

◆ lttng_notification_channel_get_next_notification()

◆ lttng_notification_channel_has_pending_notification()

◆ lttng_notification_channel_subscribe()

◆ lttng_notification_channel_unsubscribe()

◆ lttng_notification_destroy()

◆ lttng_notification_get_condition()

◆ lttng_notification_get_evaluation()

◆ lttng_notification_get_trigger()

Variable Documentation

◆ lttng_session_daemon_notification_endpoint