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