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
  40   /**
  41    * This is a doubly linked list.
  42    */
  43   struct SubscriberList *next;
  44
  45   /**
  46    * This is a doubly linked list.
  47    */
  48   struct SubscriberList *prev;
  49
  50   /**
  51    * Overall context this subscriber belongs to.
  52    */
  53   struct GNUNET_NotificationContext *nc;
  54
  55   /**
  56    * Handle where we registered with @e mq to be told about
  57    * the MQ's destruction.
  58    */
  59   struct GNUNET_MQ_DestroyNotificationHandle *mq_nh;
  60
  61   /**
  62    * Message queue for the subscriber.
  63    */
  64   struct GNUNET_MQ_Handle *mq;
  65
  66 };
  67
  68
  69 /**
  70  * The notification context is the key datastructure for a convenience
  71  * API used for transmission of notifications to the subscriber until the
  72  * subscriber disconnects (or the notification context is destroyed, in
  73  * which case we disconnect these subscribers).  Essentially, all
  74  * (notification) messages are queued up until the subscriber is able to
  75  * read them.
  76  */
  77 struct GNUNET_NotificationContext
  78 {
  79
  80   /**
  81    * Head of list of subscribers receiving notifications.
  82    */
  83   struct SubscriberList *subscribers_head;
  84
  85   /**
  86    * Tail of list of subscribers receiving notifications.
  87    */
  88   struct SubscriberList *subscribers_tail;
  89
  90   /**
  91    * Maximum number of optional messages to queue per subscriber.
  92    */
  93   unsigned int queue_length;
  94
  95 };
  96
  97
  98 /**
  99  * Subscriber has disconnected, clean up.
 100  *
 101  * @param cls our `struct SubscriberList *`
 102  */
 103 static void
 104 handle_mq_destroy (void *cls)
 105 {
 106   struct SubscriberList *pos = cls;
 107   struct GNUNET_NotificationContext *nc = pos->nc;
 108
 109   GNUNET_CONTAINER_DLL_remove (nc->subscribers_head,
 110                                nc->subscribers_tail,
 111                                pos);
 112   GNUNET_free (pos);
 113 }
 114
 115
 116 /**
 117  * Create a new notification context.
 118  *
 119  * @param queue_length maximum number of messages to keep in
 120  *        the notification queue; optional messages are dropped
 121  *        if the queue gets longer than this number of messages
 122  * @return handle to the notification context
 123  */
 124 struct GNUNET_NotificationContext *
 125 GNUNET_notification_context_create (unsigned int queue_length)
 126 {
 127   struct GNUNET_NotificationContext *nc;
 128
 129   nc = GNUNET_new (struct GNUNET_NotificationContext);
 130   nc->queue_length = queue_length;
 131   return nc;
 132 }
 133
 134
 135 /**
 136  * Destroy the context, force disconnect for all subscribers.
 137  *
 138  * @param nc context to destroy.
 139  */
 140 void
 141 GNUNET_notification_context_destroy (struct GNUNET_NotificationContext *nc)
 142 {
 143   struct SubscriberList *pos;
 144
 145   while (NULL != (pos = nc->subscribers_head))
 146   {
 147     GNUNET_CONTAINER_DLL_remove (nc->subscribers_head,
 148                                  nc->subscribers_tail,
 149                                  pos);
 150     GNUNET_MQ_destroy_notify_cancel (pos->mq_nh);
 151     GNUNET_free (pos);
 152   }
 153   GNUNET_free (nc);
 154 }
 155
 156
 157 /**
 158  * Add a subscriber to the notification context.
 159  *
 160  * @param nc context to modify
 161  * @param mq message queue add
 162  */
 163 void
 164 GNUNET_notification_context_add (struct GNUNET_NotificationContext *nc,
 165                                  struct GNUNET_MQ_Handle *mq)
 166 {
 167   struct SubscriberList *cl;
 168
 169   for (cl = nc->subscribers_head; NULL != cl; cl = cl->next)
 170     if (cl->mq == mq)
 171       return; /* already present */
 172   cl = GNUNET_new (struct SubscriberList);
 173   GNUNET_CONTAINER_DLL_insert (nc->subscribers_head,
 174                                nc->subscribers_tail,
 175                                cl);
 176   cl->nc = nc;
 177   cl->mq = mq;
 178   cl->mq_nh = GNUNET_MQ_destroy_notify (cl->mq,
 179                                         &handle_mq_destroy,
 180                                         cl);
 181 }
 182
 183
 184 /**
 185  * Send a message to all subscribers of this context.
 186  *
 187  * @param nc context to modify
 188  * @param msg message to send
 189  * @param can_drop can this message be dropped due to queue length limitations
 190  */
 191 void
 192 GNUNET_notification_context_broadcast (struct GNUNET_NotificationContext *nc,
 193                                        const struct GNUNET_MessageHeader *msg,
 194                                        int can_drop)
 195 {
 196   struct SubscriberList *pos;
 197   struct GNUNET_MQ_Envelope *env;
 198
 199   for (pos = nc->subscribers_head; NULL != pos; pos = pos->next)
 200   {
 201     if ( (GNUNET_YES == can_drop) &&
 202          (GNUNET_MQ_get_length (pos->mq) > nc->queue_length) )
 203       continue;
 204     env = GNUNET_MQ_msg_copy (msg);
 205     GNUNET_MQ_send (pos->mq,
 206                     env);
 207   }
 208 }
 209
 210
 211 /**
 212  * Return active number of subscribers in this context.
 213  *
 214  * @param nc context to query
 215  * @return number of current subscribers
 216  */
 217 unsigned int
 218 GNUNET_notification_context_get_size (struct GNUNET_NotificationContext *nc)
 219 {
 220   unsigned int num;
 221   struct SubscriberList *pos;
 222
 223   num = 0;
 224   for (pos = nc->subscribers_head; NULL != pos; pos = pos->next)
 225     num++;
 226   return num;
 227 }
 228
 229 /* end of nc.c */