src/util/nc.c

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010, 2016 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @file util/nc.c
  23  * @brief convenience functions for transmission of
  24  *        messages to multiple clients
  25  * @author Christian Grothoff
  26  */
  27
  28 #include "platform.h"
  29 #include "gnunet_util_lib.h"
  30
  31 #define LOG(kind, ...) GNUNET_log_from(kind, "util-nc", __VA_ARGS__)
  32
  33
  34 /**
  35  * Lists of subscribers we manage for notifications.
  36  */
  37 struct SubscriberList {
  38   /**
  39    * This is a doubly linked list.
  40    */
  41   struct SubscriberList *next;
  42
  43   /**
  44    * This is a doubly linked list.
  45    */
  46   struct SubscriberList *prev;
  47
  48   /**
  49    * Overall context this subscriber belongs to.
  50    */
  51   struct GNUNET_NotificationContext *nc;
  52
  53   /**
  54    * Handle where we registered with @e mq to be told about
  55    * the MQ's destruction.
  56    */
  57   struct GNUNET_MQ_DestroyNotificationHandle *mq_nh;
  58
  59   /**
  60    * Message queue for the subscriber.
  61    */
  62   struct GNUNET_MQ_Handle *mq;
  63 };
  64
  65
  66 /**
  67  * The notification context is the key datastructure for a convenience
  68  * API used for transmission of notifications to the subscriber until the
  69  * subscriber disconnects (or the notification context is destroyed, in
  70  * which case we disconnect these subscribers).  Essentially, all
  71  * (notification) messages are queued up until the subscriber is able to
  72  * read them.
  73  */
  74 struct GNUNET_NotificationContext {
  75   /**
  76    * Head of list of subscribers receiving notifications.
  77    */
  78   struct SubscriberList *subscribers_head;
  79
  80   /**
  81    * Tail of list of subscribers receiving notifications.
  82    */
  83   struct SubscriberList *subscribers_tail;
  84
  85   /**
  86    * Maximum number of optional messages to queue per subscriber.
  87    */
  88   unsigned int queue_length;
  89 };
  90
  91
  92 /**
  93  * Subscriber has disconnected, clean up.
  94  *
  95  * @param cls our `struct SubscriberList *`
  96  */
  97 static void
  98 handle_mq_destroy(void *cls)
  99 {
 100   struct SubscriberList *pos = cls;
 101   struct GNUNET_NotificationContext *nc = pos->nc;
 102
 103   GNUNET_CONTAINER_DLL_remove(nc->subscribers_head,
 104                               nc->subscribers_tail,
 105                               pos);
 106   GNUNET_free(pos);
 107 }
 108
 109
 110 /**
 111  * Create a new notification context.
 112  *
 113  * @param queue_length maximum number of messages to keep in
 114  *        the notification queue; optional messages are dropped
 115  *        if the queue gets longer than this number of messages
 116  * @return handle to the notification context
 117  */
 118 struct GNUNET_NotificationContext *
 119 GNUNET_notification_context_create(unsigned int queue_length)
 120 {
 121   struct GNUNET_NotificationContext *nc;
 122
 123   nc = GNUNET_new(struct GNUNET_NotificationContext);
 124   nc->queue_length = queue_length;
 125   return nc;
 126 }
 127
 128
 129 /**
 130  * Destroy the context, force disconnect for all subscribers.
 131  *
 132  * @param nc context to destroy.
 133  */
 134 void
 135 GNUNET_notification_context_destroy(struct GNUNET_NotificationContext *nc)
 136 {
 137   struct SubscriberList *pos;
 138
 139   while (NULL != (pos = nc->subscribers_head))
 140     {
 141       GNUNET_CONTAINER_DLL_remove(nc->subscribers_head,
 142                                   nc->subscribers_tail,
 143                                   pos);
 144       GNUNET_MQ_destroy_notify_cancel(pos->mq_nh);
 145       GNUNET_free(pos);
 146     }
 147   GNUNET_free(nc);
 148 }
 149
 150
 151 /**
 152  * Add a subscriber to the notification context.
 153  *
 154  * @param nc context to modify
 155  * @param mq message queue add
 156  */
 157 void
 158 GNUNET_notification_context_add(struct GNUNET_NotificationContext *nc,
 159                                 struct GNUNET_MQ_Handle *mq)
 160 {
 161   struct SubscriberList *cl;
 162
 163   for (cl = nc->subscribers_head; NULL != cl; cl = cl->next)
 164     if (cl->mq == mq)
 165       return;
 166   /* already present */
 167   cl = GNUNET_new(struct SubscriberList);
 168   GNUNET_CONTAINER_DLL_insert(nc->subscribers_head,
 169                               nc->subscribers_tail,
 170                               cl);
 171   cl->nc = nc;
 172   cl->mq = mq;
 173   cl->mq_nh = GNUNET_MQ_destroy_notify(cl->mq,
 174                                        &handle_mq_destroy,
 175                                        cl);
 176 }
 177
 178
 179 /**
 180  * Send a message to all subscribers of this context.
 181  *
 182  * @param nc context to modify
 183  * @param msg message to send
 184  * @param can_drop can this message be dropped due to queue length limitations
 185  */
 186 void
 187 GNUNET_notification_context_broadcast(struct GNUNET_NotificationContext *nc,
 188                                       const struct GNUNET_MessageHeader *msg,
 189                                       int can_drop)
 190 {
 191   struct SubscriberList *pos;
 192   struct GNUNET_MQ_Envelope *env;
 193
 194   for (pos = nc->subscribers_head; NULL != pos; pos = pos->next)
 195     {
 196       if ((GNUNET_YES == can_drop) &&
 197           (GNUNET_MQ_get_length(pos->mq) > nc->queue_length))
 198         continue;
 199       env = GNUNET_MQ_msg_copy(msg);
 200       GNUNET_MQ_send(pos->mq,
 201                      env);
 202     }
 203 }
 204
 205
 206 /**
 207  * Return active number of subscribers in this context.
 208  *
 209  * @param nc context to query
 210  * @return number of current subscribers
 211  */
 212 unsigned int
 213 GNUNET_notification_context_get_size(struct GNUNET_NotificationContext *nc)
 214 {
 215   unsigned int num;
 216   struct SubscriberList *pos;
 217
 218   num = 0;
 219   for (pos = nc->subscribers_head; NULL != pos; pos = pos->next)
 220     num++;
 221   return num;
 222 }
 223
 224 /* end of nc.c */