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