include/lttng/notification/channel.h

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