src/bin/lttng-sessiond/notification-thread.h

   1 /*
   2  * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License, version 2 only, as
   6  * published by the Free Software Foundation.
   7  *
   8  * This program 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 General Public License for
  11  * more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along with
  14  * this program; if not, write to the Free Software Foundation, Inc., 51
  15  * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  16  */
  17
  18 #ifndef NOTIFICATION_THREAD_H
  19 #define NOTIFICATION_THREAD_H
  20
  21 #include <urcu/list.h>
  22 #include <urcu.h>
  23 #include <urcu/rculfhash.h>
  24 #include <lttng/trigger/trigger.h>
  25 #include <common/pipe.h>
  26 #include <common/compat/poll.h>
  27 #include <common/hashtable/hashtable.h>
  28 #include <pthread.h>
  29
  30 struct notification_thread_handle {
  31         /*
  32          * Queue of struct notification command.
  33          * event_pipe must be WRITE(2) to signal that a new command
  34          * has been enqueued.
  35          */
  36         struct {
  37                 struct lttng_pipe *event_pipe;
  38                 struct cds_list_head list;
  39                 pthread_mutex_t lock;
  40         } cmd_queue;
  41         /*
  42          * Read side of pipes used to receive channel status info collected
  43          * by the various consumer daemons.
  44          */
  45         struct {
  46                 int ust32_consumer;
  47                 int ust64_consumer;
  48                 int kernel_consumer;
  49         } channel_monitoring_pipes;
  50 };
  51
  52 /**
  53  * This thread maintains an internal state associating clients and triggers.
  54  *
  55  * In order to speed-up and simplify queries, hash tables providing the
  56  * following associations are maintained:
  57  *
  58  *   - client_socket_ht: associate a client's socket (fd) to its "struct client"
  59  *             This hash table owns the "struct client" which must thus be
  60  *             disposed-of on removal from the hash table.
  61  *
  62  *   - channel_triggers_ht:
  63  *             associates a channel key to a list of
  64  *             struct lttng_trigger_list_nodes. The triggers in this list are
  65  *             those that have conditions that apply to this channel.
  66  *             A channel entry is only created when a channel is added; the
  67  *             list of triggers applying to such a channel is built at that
  68  *             moment.
  69  *             This hash table owns the list, but not the triggers themselves.
  70  *
  71  *   - channel_state_ht:
  72  *             associates a pair (channel key, channel domain) to its last
  73  *             sampled state received from the consumer daemon
  74  *             (struct channel_state).
  75  *             This previous sample is kept to implement edge-triggered
  76  *             conditions as we need to detect the state transitions.
  77  *             This hash table owns the channel state.
  78  *
  79  *   - notification_trigger_clients_ht:
  80  *             associates notification-emitting triggers to clients
  81  *             (struct notification_client_list) subscribed to those
  82  *             conditions.
  83  *             The condition's hash and match functions are used directly since
  84  *             all triggers in this hash table have the "notify" action.
  85  *             This hash table holds no ownership.
  86  *
  87  *   - channels_ht:
  88  *             associates a channel_key to a struct channel_info. The hash table
  89  *             holds the ownership of the struct channel_info.
  90  *
  91  *   - triggers_ht:
  92  *             associated a condition to a struct lttng_trigger_ht_element.
  93  *             The hash table holds the ownership of the
  94  *             lttng_trigger_ht_elements along with the triggers themselves.
  95  *
  96  * The thread reacts to the following internal events:
  97  *   1) creation of a tracing channel,
  98  *   2) destruction of a tracing channel,
  99  *   3) registration of a trigger,
 100  *   4) unregistration of a trigger,
 101  *   5) reception of a channel monitor sample from the consumer daemon.
 102  *
 103  * Events specific to notification-emitting triggers:
 104  *   6) connection of a notification client,
 105  *   7) disconnection of a notification client,
 106  *   8) subscription of a client to a conditions' notifications,
 107  *   9) unsubscription of a client from a conditions' notifications,
 108  *
 109  *
 110  * 1) Creation of a tracing channel
 111  *    - notification_trigger_clients_ht is traversed to identify
 112  *      triggers which apply to this new channel,
 113  *    - triggers identified are added to the channel_triggers_ht.
 114  *    - add channel to channels_ht
 115  *
 116  * 2) Destruction of a tracing channel
 117  *    - remove entry from channel_triggers_ht, releasing the list wrapper and
 118  *      elements,
 119  *    - remove entry from the channel_state_ht.
 120  *    - remove channel from channels_ht
 121  *
 122  * 3) Registration of a trigger
 123  *    - if the trigger's action is of type "notify",
 124  *      - traverse the list of conditions of every client to build a list of
 125  *        clients which have to be notified when this trigger's condition is met,
 126  *        - add list of clients (even if it is empty) to the
 127  *          notification_trigger_clients_ht,
 128  *    - add trigger to channel_triggers_ht (if applicable),
 129  *    - add trigger to triggers_ht
 130  *    - evaluate the trigger's condition right away to react if that condition
 131  *      is true from the beginning.
 132  *
 133  * 4) Unregistration of a trigger
 134  *    - if the trigger's action is of type "notify",
 135  *      - remove the trigger from the notification_trigger_clients_ht,
 136  *    - remove trigger from channel_triggers_ht (if applicable),
 137  *    - remove trigger from triggers_ht
 138  *
 139  * 5) Reception of a channel monitor sample from the consumer daemon
 140  *    - evaluate the conditions associated with the triggers found in
 141  *      the channel_triggers_ht,
 142  *      - if a condition evaluates to "true" and the condition is of type
 143  *        "notify", query the notification_trigger_clients_ht and send
 144  *        a notification to the clients.
 145  *
 146  * 6) Connection of a client
 147  *    - add client socket to the client_socket_ht.
 148  *
 149  * 7) Disconnection of a client
 150  *    - remove client socket from the client_socket_ht,
 151  *    - traverse all conditions to which the client is subscribed and remove
 152  *      the client from the notification_trigger_clients_ht.
 153  *
 154  * 8) Subscription of a client to a condition's notifications
 155  *    - Add the condition to the client's list of subscribed conditions,
 156  *    - Look-up notification_trigger_clients_ht and add the client to
 157  *      list of clients.
 158  *    - Evaluate the condition for the client that subscribed if the trigger
 159  *      was already registered.
 160  *
 161  * 9) Unsubscription of a client to a condition's notifications
 162  *    - Remove the condition from the client's list of subscribed conditions,
 163  *    - Look-up notification_trigger_clients_ht and remove the client
 164  *      from the list of clients.
 165  */
 166 struct notification_thread_state {
 167         int notification_channel_socket;
 168         struct lttng_poll_event events;
 169         struct cds_lfht *client_socket_ht;
 170         struct cds_lfht *channel_triggers_ht;
 171         struct cds_lfht *channel_state_ht;
 172         struct cds_lfht *notification_trigger_clients_ht;
 173         struct cds_lfht *channels_ht;
 174         struct cds_lfht *triggers_ht;
 175 };
 176
 177 /* notification_thread_data takes ownership of the channel monitor pipes. */
 178 struct notification_thread_handle *notification_thread_handle_create(
 179                 struct lttng_pipe *ust32_channel_monitor_pipe,
 180                 struct lttng_pipe *ust64_channel_monitor_pipe,
 181                 struct lttng_pipe *kernel_channel_monitor_pipe);
 182 void notification_thread_handle_destroy(
 183                 struct notification_thread_handle *handle);
 184
 185 void *thread_notification(void *data);
 186
 187 #endif /* NOTIFICATION_THREAD_H */