From: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Date: Tue, 1 Aug 2017 18:23:43 +0000 (-0400)
Subject: Docs: document the notification channel API
X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=commitdiff_plain;h=92eda4bd141a72dca012cf3aca1faf5a54000203

Docs: document the notification channel API

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---

diff --git a/include/lttng/notification/channel.h b/include/lttng/notification/channel.h
index 50334c58e..232564633 100644
--- a/include/lttng/notification/channel.h
+++ b/include/lttng/notification/channel.h
@@ -27,7 +27,6 @@ struct lttng_condition;
 struct lttng_notification;
 struct lttng_notification_channel;
 
-/* LTTng Notification channel */
 enum lttng_notification_channel_status {
 	LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1,
 	LTTNG_NOTIFICATION_CHANNEL_STATUS_OK = 0,
@@ -40,24 +39,97 @@ enum lttng_notification_channel_status {
 	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 notificationon success,
+ * LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
+ * provided, or LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED if
+ * notifications were dropped.
+ */
 extern enum lttng_notification_channel_status
 lttng_notification_channel_get_next_notification(
 		struct lttng_notification_channel *channel,
 		struct lttng_notification **notification);
 
+/*
+ * 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);