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

/*
 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

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