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