From: Jérémie Galarneau Date: Wed, 26 Jul 2017 18:46:35 +0000 (-0400) Subject: Docs: move notification thread documentation to header X-Git-Tag: v2.11.0-rc1~507 X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=74df9916833ae6a69520c1a49ddce44ba3eea078 Docs: move notification thread documentation to header Signed-off-by: Jérémie Galarneau --- diff --git a/src/bin/lttng-sessiond/notification-thread.c b/src/bin/lttng-sessiond/notification-thread.c index c652b6ee8..b580faa26 100644 --- a/src/bin/lttng-sessiond/notification-thread.c +++ b/src/bin/lttng-sessiond/notification-thread.c @@ -42,114 +42,6 @@ #include #include -/** - * This thread maintains an internal state associating clients and triggers. - * - * In order to speed-up and simplify queries, hash tables providing the - * following associations are maintained: - * - * - client_socket_ht: associate a client's socket (fd) to its "struct client" - * This hash table owns the "struct client" which must thus be - * disposed-of on removal from the hash table. - * - * - channel_triggers_ht: - * associates a channel key to a list of - * struct lttng_trigger_list_nodes. The triggers in this list are - * those that have conditions that apply to this channel. - * This hash table owns the list, but not the triggers themselves. - * - * - channel_state_ht: - * associates a pair (channel key, channel domain) to its last - * sampled state received from the consumer daemon - * (struct channel_state). - * This previous sample is kept to implement edge-triggered - * conditions as we need to detect the state transitions. - * This hash table owns the channel state. - * - * - notification_trigger_clients_ht: - * associates notification-emitting triggers to clients - * (struct notification_client_list) subscribed to those - * conditions. - * The condition's hash and match functions are used directly since - * all triggers in this hash table have the "notify" action. - * This hash table holds no ownership. - * - * - channels_ht: - * associates a channel_key to a struct channel_info. The hash table - * holds the ownership of the struct channel_info. - * - * - triggers_ht: - * associated a condition to a struct lttng_trigger_ht_element. - * The hash table holds the ownership of the - * lttng_trigger_ht_elements along with the triggers themselves. - * - * The thread reacts to the following internal events: - * 1) creation of a tracing channel, - * 2) destruction of a tracing channel, - * 3) registration of a trigger, - * 4) unregistration of a trigger, - * 5) reception of a channel monitor sample from the consumer daemon. - * - * Events specific to notification-emitting triggers: - * 6) connection of a notification client, - * 7) disconnection of a notification client, - * 8) subscription of a client to a conditions' notifications, - * 9) unsubscription of a client from a conditions' notifications, - * - * - * 1) Creation of a tracing channel - * - notification_trigger_clients_ht is traversed to identify - * triggers which apply to this new channel, - * - triggers identified are added to the channel_triggers_ht. - * - add channel to channels_ht - * - * 2) Destruction of a tracing channel - * - remove entry from channel_triggers_ht, releasing the list wrapper and - * elements, - * - remove entry from the channel_state_ht. - * - remove channel from channels_ht - * - * 3) Registration of a trigger - * - if the trigger's action is of type "notify", - * - traverse the list of conditions of every client to build a list of - * clients which have to be notified when this trigger's condition is met, - * - add list of clients (even if it is empty) to the - * notification_trigger_clients_ht, - * - add trigger to channel_triggers_ht (if applicable), - * - add trigger to triggers_ht - * - * 4) Unregistration of a trigger - * - if the trigger's action is of type "notify", - * - remove the trigger from the notification_trigger_clients_ht, - * - remove trigger from channel_triggers_ht (if applicable), - * - remove trigger from triggers_ht - * - * 5) Reception of a channel monitor sample from the consumer daemon - * - evaluate the conditions associated with the triggers found in - * the channel_triggers_ht, - * - if a condition evaluates to "true" and the condition is of type - * "notify", query the notification_trigger_clients_ht and send - * a notification to the clients. - * - * 6) Connection of a client - * - add client socket to the client_socket_ht. - * - * 7) Disconnection of a client - * - remove client socket from the client_socket_ht, - * - traverse all conditions to which the client is subscribed and remove - * the client from the notification_trigger_clients_ht. - * - * 8) Subscription of a client to a condition's notifications - * - Add the condition to the client's list of subscribed conditions, - * - Look-up notification_trigger_clients_ht and add the client to - * list of clients. - * - * 9) Unsubscription of a client to a condition's notifications - * - Remove the condition from the client's list of subscribed conditions, - * - Look-up notification_trigger_clients_ht and remove the client - * from the list of clients. - */ - /* * Destroy the thread data previously created by the init function. */ diff --git a/src/bin/lttng-sessiond/notification-thread.h b/src/bin/lttng-sessiond/notification-thread.h index c401b410b..a9c771104 100644 --- a/src/bin/lttng-sessiond/notification-thread.h +++ b/src/bin/lttng-sessiond/notification-thread.h @@ -49,6 +49,116 @@ struct notification_thread_handle { } channel_monitoring_pipes; }; +/** + * This thread maintains an internal state associating clients and triggers. + * + * In order to speed-up and simplify queries, hash tables providing the + * following associations are maintained: + * + * - client_socket_ht: associate a client's socket (fd) to its "struct client" + * This hash table owns the "struct client" which must thus be + * disposed-of on removal from the hash table. + * + * - channel_triggers_ht: + * associates a channel key to a list of + * struct lttng_trigger_list_nodes. The triggers in this list are + * those that have conditions that apply to this channel. + * A channel entry is only created when a channel is added; the + * list of triggers applying to such a channel is built at that + * moment. + * This hash table owns the list, but not the triggers themselves. + * + * - channel_state_ht: + * associates a pair (channel key, channel domain) to its last + * sampled state received from the consumer daemon + * (struct channel_state). + * This previous sample is kept to implement edge-triggered + * conditions as we need to detect the state transitions. + * This hash table owns the channel state. + * + * - notification_trigger_clients_ht: + * associates notification-emitting triggers to clients + * (struct notification_client_list) subscribed to those + * conditions. + * The condition's hash and match functions are used directly since + * all triggers in this hash table have the "notify" action. + * This hash table holds no ownership. + * + * - channels_ht: + * associates a channel_key to a struct channel_info. The hash table + * holds the ownership of the struct channel_info. + * + * - triggers_ht: + * associated a condition to a struct lttng_trigger_ht_element. + * The hash table holds the ownership of the + * lttng_trigger_ht_elements along with the triggers themselves. + * + * The thread reacts to the following internal events: + * 1) creation of a tracing channel, + * 2) destruction of a tracing channel, + * 3) registration of a trigger, + * 4) unregistration of a trigger, + * 5) reception of a channel monitor sample from the consumer daemon. + * + * Events specific to notification-emitting triggers: + * 6) connection of a notification client, + * 7) disconnection of a notification client, + * 8) subscription of a client to a conditions' notifications, + * 9) unsubscription of a client from a conditions' notifications, + * + * + * 1) Creation of a tracing channel + * - notification_trigger_clients_ht is traversed to identify + * triggers which apply to this new channel, + * - triggers identified are added to the channel_triggers_ht. + * - add channel to channels_ht + * + * 2) Destruction of a tracing channel + * - remove entry from channel_triggers_ht, releasing the list wrapper and + * elements, + * - remove entry from the channel_state_ht. + * - remove channel from channels_ht + * + * 3) Registration of a trigger + * - if the trigger's action is of type "notify", + * - traverse the list of conditions of every client to build a list of + * clients which have to be notified when this trigger's condition is met, + * - add list of clients (even if it is empty) to the + * notification_trigger_clients_ht, + * - add trigger to channel_triggers_ht (if applicable), + * - add trigger to triggers_ht + * + * 4) Unregistration of a trigger + * - if the trigger's action is of type "notify", + * - remove the trigger from the notification_trigger_clients_ht, + * - remove trigger from channel_triggers_ht (if applicable), + * - remove trigger from triggers_ht + * + * 5) Reception of a channel monitor sample from the consumer daemon + * - evaluate the conditions associated with the triggers found in + * the channel_triggers_ht, + * - if a condition evaluates to "true" and the condition is of type + * "notify", query the notification_trigger_clients_ht and send + * a notification to the clients. + * + * 6) Connection of a client + * - add client socket to the client_socket_ht. + * + * 7) Disconnection of a client + * - remove client socket from the client_socket_ht, + * - traverse all conditions to which the client is subscribed and remove + * the client from the notification_trigger_clients_ht. + * + * 8) Subscription of a client to a condition's notifications + * - Add the condition to the client's list of subscribed conditions, + * - Look-up notification_trigger_clients_ht and add the client to + * list of clients. + * + * 9) Unsubscription of a client to a condition's notifications + * - Remove the condition from the client's list of subscribed conditions, + * - Look-up notification_trigger_clients_ht and remove the client + * from the list of clients. + */ struct notification_thread_state { int notification_channel_socket; struct lttng_poll_event events;