include/lttng/notification/channel.h

   1 /*
   2  * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_NOTIFICATION_CHANNEL_H
   9 #define LTTNG_NOTIFICATION_CHANNEL_H
  10
  11 #include <stdbool.h>
  12
  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
  22 enum lttng_notification_channel_status {
  23         LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED = 1,
  24         LTTNG_NOTIFICATION_CHANNEL_STATUS_INTERRUPTED = 2,
  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
  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  */
  60 extern struct lttng_notification_channel *lttng_notification_channel_create(
  61                 struct lttng_endpoint *endpoint);
  62
  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  *
  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.
  83  */
  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
  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  *
 100  * Returns
 101  *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_OK on success,
 102  *   - LTTNG_NOTIFICATION_CHANNEL_STATUS_INVALID if an invalid parameter was
 103  *     provided.
 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
 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  *
 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.
 124  */
 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
 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  *
 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.
 144  */
 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
 150 /*
 151  * Closes and destroys (frees) a notification channel.
 152  */
 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 */