src/include/gnunet_bandwidth_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Functions related to bandwidth (unit)
  26  *
  27  * @defgroup bandwidth  Bandwidth library
  28  * Functions related to bandwidth (unit)
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_BANDWIDTH_LIB_H
  33 #define GNUNET_BANDWIDTH_LIB_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_common.h"
  44 #include "gnunet_time_lib.h"
  45
  46 GNUNET_NETWORK_STRUCT_BEGIN
  47
  48 /**
  49  * 32-bit bandwidth used for network exchange by GNUnet, in bytes per second.
  50  */
  51 struct GNUNET_BANDWIDTH_Value32NBO
  52 {
  53   /**
  54    * The actual value (bytes per second).
  55    */
  56   uint32_t value__ GNUNET_PACKED;
  57 };
  58 GNUNET_NETWORK_STRUCT_END
  59
  60
  61 /**
  62  * Callback to be called by the bandwidth tracker if the tracker
  63  * was updated and the client should update it's delay values
  64  *
  65  * @param cls a closure to pass
  66  */
  67 typedef void
  68 (*GNUNET_BANDWIDTH_TrackerUpdateCallback) (void *cls);
  69
  70
  71 /**
  72  * Callback to be called by the bandwidth tracker if the tracker
  73  * was updated and the client should update it's delay values
  74  *
  75  * @param cls a closure to pass
  76  */
  77 typedef void
  78 (*GNUNET_BANDWIDTH_ExcessNotificationCallback) (void *cls);
  79
  80
  81 /**
  82  * Struct to track available bandwidth.  Combines a time stamp with a
  83  * number of bytes transmitted, a quota and a maximum amount that
  84  * carries over.  Not opaque so that it can be inlined into data
  85  * structures (reducing malloc-ing); however, values should not be
  86  * accessed directly by clients (hence the '__').
  87  */
  88 struct GNUNET_BANDWIDTH_Tracker
  89 {
  90   /**
  91    * Closure for @e update_cb.
  92    */
  93   void *update_cb_cls;
  94
  95   /**
  96    * Function we call if the tracker's bandwidth is increased and a
  97    * previously returned timeout might now expire earlier.
  98    */
  99   GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb;
 100
 101   /**
 102    * Closure for @e excess_cb.
 103    */
 104   void *excess_cb_cls;
 105
 106   /**
 107    * Function we call if the tracker is about to throw
 108    * away bandwidth due to excess (max carry exceeded).
 109    */
 110   GNUNET_BANDWIDTH_ExcessNotificationCallback excess_cb;
 111
 112   /**
 113    * Number of bytes consumed since we last updated the tracker.
 114    */
 115   int64_t consumption_since_last_update__;
 116
 117   /**
 118    * Task scheduled to call the @e excess_cb once we have
 119    * reached the maximum bandwidth the tracker can hold.
 120    */
 121   struct GNUNET_SCHEDULER_Task *excess_task;
 122
 123   /**
 124    * Time when we last updated the tracker.
 125    */
 126   struct GNUNET_TIME_Absolute last_update__;
 127
 128   /**
 129    * Bandwidth limit to enforce in bytes per second.
 130    */
 131   uint32_t available_bytes_per_s__;
 132
 133   /**
 134    * Maximum number of seconds over which bandwidth may "accumulate".
 135    * Note that additionally, we also always allow at least
 136    * #GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate.
 137    */
 138   uint32_t max_carry_s__;
 139 };
 140
 141
 142 /**
 143  * Convenience definition to use for 0-bandwidth.
 144  */
 145 #define GNUNET_BANDWIDTH_ZERO GNUNET_BANDWIDTH_value_init (0)
 146
 147
 148 /**
 149  * Create a new bandwidth value.
 150  *
 151  * @param bytes_per_second value to create
 152  * @return the new bandwidth value
 153  */
 154 struct GNUNET_BANDWIDTH_Value32NBO
 155 GNUNET_BANDWIDTH_value_init (uint32_t bytes_per_second);
 156
 157
 158 /**
 159  * Maximum possible bandwidth value.
 160  */
 161 #define GNUNET_BANDWIDTH_VALUE_MAX GNUNET_BANDWIDTH_value_init(UINT32_MAX)
 162
 163
 164 /**
 165  * At the given bandwidth, calculate how much traffic will be
 166  * available until the given deadline.
 167  *
 168  * @param bps bandwidth
 169  * @param deadline when is the deadline
 170  * @return number of bytes available at bps until deadline
 171  */
 172 uint64_t
 173 GNUNET_BANDWIDTH_value_get_available_until (struct GNUNET_BANDWIDTH_Value32NBO bps,
 174                                             struct GNUNET_TIME_Relative deadline);
 175
 176
 177 /**
 178  * At the given bandwidth, calculate how long it would take for
 179  * 'size' bytes to be transmitted.
 180  *
 181  * @param bps bandwidth
 182  * @param size number of bytes we want to have available
 183  * @return how long it would take
 184  */
 185 struct GNUNET_TIME_Relative
 186 GNUNET_BANDWIDTH_value_get_delay_for (struct GNUNET_BANDWIDTH_Value32NBO bps,
 187                                       uint64_t size);
 188
 189
 190 /**
 191  * Compute the MIN of two bandwidth values.
 192  *
 193  * @param b1 first value
 194  * @param b2 second value
 195  * @return the min of b1 and b2
 196  */
 197 struct GNUNET_BANDWIDTH_Value32NBO
 198 GNUNET_BANDWIDTH_value_min (struct GNUNET_BANDWIDTH_Value32NBO b1,
 199                             struct GNUNET_BANDWIDTH_Value32NBO b2);
 200
 201
 202 /**
 203  * Compute the MAX of two bandwidth values.
 204  *
 205  * @param b1 first value
 206  * @param b2 second value
 207  * @return the min of b1 and b2
 208  */
 209 struct GNUNET_BANDWIDTH_Value32NBO
 210 GNUNET_BANDWIDTH_value_max (struct GNUNET_BANDWIDTH_Value32NBO b1,
 211                             struct GNUNET_BANDWIDTH_Value32NBO b2);
 212
 213
 214 /**
 215  * Initialize bandwidth tracker.  Note that in addition to the
 216  * 'max_carry_s' limit, we also always allow at least
 217  * #GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate.  So if the
 218  * bytes-per-second limit is so small that within 'max_carry_s' not
 219  * even #GNUNET_SERVER_MAX_MESSAGE_SIZE is allowed to accumulate, it is
 220  * ignored and replaced by #GNUNET_SERVER_MAX_MESSAGE_SIZE (which is in
 221  * bytes).
 222  *
 223  * @param av tracker to initialize
 224  * @param update_cb callback to notify a client about the tracker being updated
 225  * @param update_cb_cls cls for the @a update_cb callback
 226  * @param bytes_per_second_limit initial limit to assume
 227  * @param max_carry_s maximum number of seconds unused bandwidth
 228  *        may accumulate before it expires
 229  */
 230 void
 231 GNUNET_BANDWIDTH_tracker_init (struct GNUNET_BANDWIDTH_Tracker *av,
 232                                GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb,
 233                                void *update_cb_cls,
 234                                struct GNUNET_BANDWIDTH_Value32NBO bytes_per_second_limit,
 235                                uint32_t max_carry_s);
 236
 237
 238 /**
 239  * Initialize bandwidth tracker.  Note that in addition to the
 240  * 'max_carry_s' limit, we also always allow at least
 241  * GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate.  So if the
 242  * bytes-per-second limit is so small that within 'max_carry_s' not
 243  * even GNUNET_SERVER_MAX_MESSAGE_SIZE is allowed to accumulate, it is
 244  * ignored and replaced by GNUNET_SERVER_MAX_MESSAGE_SIZE (which is in
 245  * bytes).
 246  *
 247  * @param av tracker to initialize
 248  * @param update_cb callback to notify a client about the tracker being updated
 249  * @param update_cb_cls cls for the @a update_cb callback
 250  * @param bytes_per_second_limit initial limit to assume
 251  * @param max_carry_s maximum number of seconds unused bandwidth
 252  *        may accumulate before it expires
 253  * @param excess_cb callback to notify if we have excess bandwidth
 254  * @param excess_cb_cls closure for @a excess_cb
 255  */
 256 void
 257 GNUNET_BANDWIDTH_tracker_init2 (struct GNUNET_BANDWIDTH_Tracker *av,
 258                                 GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb,
 259                                 void *update_cb_cls,
 260                                 struct GNUNET_BANDWIDTH_Value32NBO bytes_per_second_limit,
 261                                 uint32_t max_carry_s,
 262                                 GNUNET_BANDWIDTH_ExcessNotificationCallback excess_cb,
 263                                 void *excess_cb_cls);
 264
 265
 266 /**
 267  * Stop notifying about tracker updates and excess notifications
 268  *
 269  * @param av the respective trackers
 270  */
 271 void
 272 GNUNET_BANDWIDTH_tracker_notification_stop (struct GNUNET_BANDWIDTH_Tracker *av);
 273
 274
 275 /**
 276  * Notify the tracker that a certain number of bytes of bandwidth have
 277  * been consumed.  Note that it is legal to consume bytes even if not
 278  * enough bandwidth is available (in that case,
 279  * #GNUNET_BANDWIDTH_tracker_get_delay() may return non-zero delay values
 280  * even for a size of zero for a while).
 281  *
 282  * @param av tracker to update
 283  * @param size number of bytes consumed
 284  * @return #GNUNET_YES if this consumption is above the limit
 285  */
 286 int
 287 GNUNET_BANDWIDTH_tracker_consume (struct GNUNET_BANDWIDTH_Tracker *av,
 288                                   ssize_t size);
 289
 290
 291 /**
 292  * Compute how long we should wait until consuming @a size
 293  * bytes of bandwidth in order to stay within the given
 294  * quota.
 295  *
 296  * @param av tracker to query
 297  * @param size number of bytes we would like to consume
 298  * @return time to wait for consumption to be OK
 299  */
 300 struct GNUNET_TIME_Relative
 301 GNUNET_BANDWIDTH_tracker_get_delay (struct GNUNET_BANDWIDTH_Tracker *av,
 302                                     size_t size);
 303
 304
 305 /**
 306  * Compute how many bytes are available for consumption right now.
 307  * quota.
 308  *
 309  * @param av tracker to query
 310  * @return number of bytes available for consumption right now
 311  */
 312 int64_t
 313 GNUNET_BANDWIDTH_tracker_get_available (struct GNUNET_BANDWIDTH_Tracker *av);
 314
 315
 316 /**
 317  * Update quota of bandwidth tracker.
 318  *
 319  * @param av tracker to initialize
 320  * @param bytes_per_second_limit new limit to assume
 321  */
 322 void
 323 GNUNET_BANDWIDTH_tracker_update_quota (struct GNUNET_BANDWIDTH_Tracker *av,
 324                                        struct GNUNET_BANDWIDTH_Value32NBO
 325                                        bytes_per_second_limit);
 326
 327
 328 #if 0                           /* keep Emacsens' auto-indent happy */
 329 {
 330 #endif
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334
 335 /* ifndef GNUNET_BANDWIDTH_LIB_H */
 336 #endif
 337
 338 /** @} */  /* end of group */
 339
 340 /* end of gnunet_bandwidth_lib.h */