[lttng-tools.git] / include / lttng / notification / channel.h

/*
 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_NOTIFICATION_CHANNEL_H
#define LTTNG_NOTIFICATION_CHANNEL_H

#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

struct lttng_endpoint;
struct lttng_condition;
struct lttng_notification;
struct lttng_notification_channel;

enum lttng_notification_channel_status {
	LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED = 2,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_OK = 0,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR = -1,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED = -2,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED = -3,
	/* Condition unknown. */
	LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION = -4,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID = -5,
	LTTNG_NOTIFICATION_CHANNEL_STATUS_UNSUPPORTED_VERSION = -6,
};

/**
 * A notification channel is used to receive notifications from various
 * LTTng components.
 *
 * Notification channels connect a client to an LTTng endpoint
 * (see lttng/endpoint.h) and allows client to subscribe and unsubscribe
 * to various types of notifications which are associated to conditions.
 *
 * In order to emit a notification, a condition must be associated to a
 * notify action within a trigger. A client wishing to consume such
 * conditions must explicitly subscribe to them by using an equivalent
 * condition.
 */

/*
 * Create a notification channel connected to a given endpoint.
 *
 * The only supported endpoint, at the moment, is the
 * lttng_session_daemon_notification_endpoint, which is a singleton
 * declared in the lttng/endpoint.h header.
 *
 * Returns an lttng_notification_channel on success, NULL on failure.
 * The returned lttng_notification_channel must be destroyed using
 * the lttng_notification_channel_destroy() function.
 */
extern struct lttng_notification_channel *lttng_notification_channel_create(
		struct lttng_endpoint *endpoint);

/*
 * Get the next notification received on a notification channel.
 *
 * This call will block until a notification is received on the notification
 * channel or until the endpoint closes the connection.
 *
 * The returned notification's ownership is transferred to the caller and
 * it must be destroyed using lttng_notification_destroy().
 *
 * Notifications can be dropped if a client consumes the notifications sent
 * through the notification channel too slowly.
 *
 * Returns
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
 *     provided,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if notifications
 *     were dropped,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED if a signal was received
 *     that caused the reception to fail.
 */
extern enum lttng_notification_channel_status
lttng_notification_channel_get_next_notification(
		struct lttng_notification_channel *channel,
		struct lttng_notification **notification);

/*
 * Check whether a notification is pending on a notification channel.
 *
 * This call allows the user to check whether a notification is pending on
 * the notification channel.
 *
 * If pending is set to true and the return value is
 * LTTNG_NOTIFICATION_CHANNEL_STATUS_OK,
 * lttng_notification_channel_get_next_notification() can be called and
 * is guaranteed to not block.
 *
 * Returns
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
 *     provided.
 */
extern enum lttng_notification_channel_status
lttng_notification_channel_has_pending_notification(
		struct lttng_notification_channel *channel,
		bool *notification_pending);

/*
 * Subscribe to notifications of a condition through a notification channel.
 *
 * The caller retains the ownership of the condition passed through this call
 * and it can be disposed-of at any moment after this call.
 *
 * An error will be reported if the client tries to subscribe to the same
 * condition multiple times without unsubscribing.
 *
 * Returns
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
 *     provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the
 *     client was already subscribed to the condition through this channel.
 */
extern enum lttng_notification_channel_status
lttng_notification_channel_subscribe(
		struct lttng_notification_channel *channel,
		const struct lttng_condition *condition);

/*
 * Unsubscribe to notifications of a condition through a notification channel.
 *
 * The caller retains the ownership of the condition passed through this call
 * and it can be disposed-of at any moment after this call.
 *
 * An error will be reported if the client tries to unsubscribe to from a
 * conditions' notifications to which it was not previously subscribed.
 *
 * Returns
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
 *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
 *     provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the
 *     client was not already subscribed to the condition through this channel.
 */
extern enum lttng_notification_channel_status
lttng_notification_channel_unsubscribe(
		struct lttng_notification_channel *channel,
		const struct lttng_condition *condition);

/*
 * Closes and destroys (frees) a notification channel.
 */
extern void lttng_notification_channel_destroy(
		struct lttng_notification_channel *channel);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_NOTIFICATION_CHANNEL_H */
Commit	Line	Data
a58c490f	1	/*
ab5be9fa	2	* Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
a58c490f	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
a58c490f	5	*
a58c490f JG	6	*/
	7
	8	#ifndef LTTNG_NOTIFICATION_CHANNEL_H
	9	#define LTTNG_NOTIFICATION_CHANNEL_H
	10
1d757b1c JG	11	#include <stdbool.h>
1d757b1c JG	12
a58c490f JG	13	#ifdef __cplusplus
	14	extern "C" {
	15	#endif
	16
	17	struct lttng_endpoint;
	18	struct lttng_condition;
	19	struct lttng_notification;
	20	struct lttng_notification_channel;
	21
a58c490f JG	22	enum lttng_notification_channel_status {
a58c490f JG	23	LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1,
f83bcd90	24	LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED = 2,
a58c490f JG	25	LTTNG_NOTIFICATION_CHANNEL_STATUS_OK = 0,
	26	LTTNG_NOTIFICATION_CHANNEL_STATUS_ERROR = -1,
	27	LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED = -2,
	28	LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED = -3,
	29	/* Condition unknown. */
	30	LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION = -4,
	31	LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID = -5,
	32	LTTNG_NOTIFICATION_CHANNEL_STATUS_UNSUPPORTED_VERSION = -6,
	33	};
	34
92eda4bd JG	35	/**
	36	* A notification channel is used to receive notifications from various
	37	* LTTng components.
	38	*
	39	* Notification channels connect a client to an LTTng endpoint
	40	* (see lttng/endpoint.h) and allows client to subscribe and unsubscribe
	41	* to various types of notifications which are associated to conditions.
	42	*
	43	* In order to emit a notification, a condition must be associated to a
	44	* notify action within a trigger. A client wishing to consume such
	45	* conditions must explicitly subscribe to them by using an equivalent
	46	* condition.
	47	*/
	48
	49	/*
	50	* Create a notification channel connected to a given endpoint.
	51	*
	52	* The only supported endpoint, at the moment, is the
	53	* lttng_session_daemon_notification_endpoint, which is a singleton
	54	* declared in the lttng/endpoint.h header.
	55	*
	56	* Returns an lttng_notification_channel on success, NULL on failure.
	57	* The returned lttng_notification_channel must be destroyed using
	58	* the lttng_notification_channel_destroy() function.
	59	*/
a58c490f JG	60	extern struct lttng_notification_channel *lttng_notification_channel_create(
	61	struct lttng_endpoint *endpoint);
	62
92eda4bd JG	63	/*
	64	* Get the next notification received on a notification channel.
	65	*
	66	* This call will block until a notification is received on the notification
	67	* channel or until the endpoint closes the connection.
	68	*
	69	* The returned notification's ownership is transferred to the caller and
	70	* it must be destroyed using lttng_notification_destroy().
	71	*
	72	* Notifications can be dropped if a client consumes the notifications sent
	73	* through the notification channel too slowly.
	74	*
f83bcd90 JG	75	* Returns
	76	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK and a notification on success,
	77	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
	78	* provided,
	79	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if notifications
	80	* were dropped,
	81	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED if a signal was received
	82	* that caused the reception to fail.
92eda4bd	83	*/
a58c490f JG	84	extern enum lttng_notification_channel_status
	85	lttng_notification_channel_get_next_notification(
	86	struct lttng_notification_channel *channel,
	87	struct lttng_notification **notification);
	88
1d757b1c JG	89	/*
	90	* Check whether a notification is pending on a notification channel.
	91	*
	92	* This call allows the user to check whether a notification is pending on
	93	* the notification channel.
	94	*
	95	* If pending is set to true and the return value is
	96	* LTTNG_NOTIFICATION_CHANNEL_STATUS_OK,
	97	* lttng_notification_channel_get_next_notification() can be called and
	98	* is guaranteed to not block.
	99	*
f83bcd90 JG	100	* Returns
	101	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
	102	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
	103	* provided.
1d757b1c JG	104	*/
	105	extern enum lttng_notification_channel_status
	106	lttng_notification_channel_has_pending_notification(
	107	struct lttng_notification_channel *channel,
	108	bool *notification_pending);
	109
92eda4bd JG	110	/*
	111	* Subscribe to notifications of a condition through a notification channel.
	112	*
	113	* The caller retains the ownership of the condition passed through this call
	114	* and it can be disposed-of at any moment after this call.
	115	*
	116	* An error will be reported if the client tries to subscribe to the same
	117	* condition multiple times without unsubscribing.
	118	*
f83bcd90 JG	119	* Returns
	120	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
	121	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
	122	* provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED if the
	123	* client was already subscribed to the condition through this channel.
92eda4bd	124	*/
a58c490f JG	125	extern enum lttng_notification_channel_status
	126	lttng_notification_channel_subscribe(
	127	struct lttng_notification_channel *channel,
	128	const struct lttng_condition *condition);
	129
92eda4bd JG	130	/*
	131	* Unsubscribe to notifications of a condition through a notification channel.
	132	*
	133	* The caller retains the ownership of the condition passed through this call
	134	* and it can be disposed-of at any moment after this call.
	135	*
	136	* An error will be reported if the client tries to unsubscribe to from a
	137	* conditions' notifications to which it was not previously subscribed.
	138	*
f83bcd90 JG	139	* Returns
	140	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
	141	* - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
	142	* provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_UNKNOWN_CONDITION if the
	143	* client was not already subscribed to the condition through this channel.
92eda4bd	144	*/
a58c490f JG	145	extern enum lttng_notification_channel_status
	146	lttng_notification_channel_unsubscribe(
	147	struct lttng_notification_channel *channel,
	148	const struct lttng_condition *condition);
	149
92eda4bd JG	150	/*
	151	* Closes and destroys (frees) a notification channel.
	152	*/
a58c490f JG	153	extern void lttng_notification_channel_destroy(
	154	struct lttng_notification_channel *channel);
	155
	156	#ifdef __cplusplus
	157	}
	158	#endif
	159
	160	#endif /* LTTNG_NOTIFICATION_CHANNEL_H */