src/include/gnunet_bandwidth_lib.h

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