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 2, 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 /**
  42  * 32-bit bandwidth used for network exchange by GNUnet, in bytes per second.
  43  */
  44 struct GNUNET_BANDWIDTH_Value32NBO
  45 {
  46   /**
  47    * The actual value (bytes per second).
  48    */
  49   uint32_t value__ GNUNET_PACKED;
  50 };
  51
  52
  53 /**
  54  * Struct to track available bandwidth.  Combines a time stamp with a
  55  * number of bytes transmitted, a quota and a maximum amount that
  56  * carries over.  Not opaque so that it can be inlined into data
  57  * structures (reducing malloc-ing); however, values should not be
  58  * accessed directly by clients (hence the '__').
  59  */
  60 struct GNUNET_BANDWIDTH_Tracker
  61 {
  62   /**
  63    * Number of bytes consumed since we last updated the tracker.
  64    */
  65   int64_t consumption_since_last_update__;
  66
  67   /**
  68    * Time when we last updated the tracker.
  69    */
  70   struct GNUNET_TIME_Absolute last_update__;
  71
  72   /**
  73    * Bandwidth limit to enforce in bytes per s.
  74    */
  75   uint32_t available_bytes_per_s__;
  76
  77   /**
  78    * Maximum number of seconds over which bandwidth may "accumulate".
  79    * Note that additionally, we also always allow at least
  80    * GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate.
  81    */
  82   uint32_t max_carry_s__;
  83 };
  84
  85
  86 /**
  87  * Create a new bandwidth value.
  88  *
  89  * @param bytes_per_second value to create
  90  * @return the new bandwidth value
  91  */
  92 struct GNUNET_BANDWIDTH_Value32NBO GNUNET_BANDWIDTH_value_init (uint32_t
  93                                                                 bytes_per_second);
  94
  95
  96 /**
  97  * Maximum possible bandwidth value.
  98  */
  99 #define GNUNET_BANDWIDTH_VALUE_MAX GNUNET_BANDWIDTH_value_init(UINT32_MAX)
 100
 101
 102 /**
 103  * At the given bandwidth, calculate how much traffic will be
 104  * available until the given deadline.
 105  *
 106  * @param bps bandwidth
 107  * @param deadline when is the deadline
 108  * @return number of bytes available at bps until deadline
 109  */
 110 uint64_t                    GNUNET_BANDWIDTH_value_get_available_until (struct
 111                                                                         GNUNET_BANDWIDTH_Value32NBO
 112                                                                         bps,
 113                                                                         struct
 114                                                                         GNUNET_TIME_Relative
 115                                                                         deadline);
 116
 117
 118 /**
 119  * At the given bandwidth, calculate how long it would take for
 120  * 'size' bytes to be transmitted.
 121  *
 122  * @param bps bandwidth
 123  * @param size number of bytes we want to have available
 124  * @return how long it would take
 125  */
 126 struct GNUNET_TIME_Relative GNUNET_BANDWIDTH_value_get_delay_for (struct
 127                                                                   GNUNET_BANDWIDTH_Value32NBO
 128                                                                   bps,
 129                                                                   uint64_t
 130                                                                   size);
 131
 132
 133
 134 /**
 135  * Compute the MIN of two bandwidth values.
 136  *
 137  * @param b1 first value
 138  * @param b2 second value
 139  * @return the min of b1 and b2
 140  */
 141 struct GNUNET_BANDWIDTH_Value32NBO GNUNET_BANDWIDTH_value_min (struct
 142                                                                GNUNET_BANDWIDTH_Value32NBO
 143                                                                b1,
 144                                                                struct
 145                                                                GNUNET_BANDWIDTH_Value32NBO
 146                                                                b2);
 147
 148
 149 /**
 150  * Initialize bandwidth tracker.  Note that in addition to the
 151  * 'max_carry_s' limit, we also always allow at least
 152  * GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate.  So if the
 153  * bytes-per-second limit is so small that within 'max_carry_s' not
 154  * even GNUNET_SERVER_MAX_MESSAGE_SIZE is allowed to accumulate, it is
 155  * ignored and replaced by GNUNET_SERVER_MAX_MESSAGE_SIZE (which is in
 156  * bytes).
 157  *
 158  * @param av tracker to initialize
 159  * @param bytes_per_second_limit initial limit to assume
 160  * @param max_carry_s maximum number of seconds unused bandwidth
 161  *        may accumulate before it expires
 162  */
 163 void GNUNET_BANDWIDTH_tracker_init (struct GNUNET_BANDWIDTH_Tracker *av,
 164                                     struct GNUNET_BANDWIDTH_Value32NBO
 165                                     bytes_per_second_limit,
 166                                     uint32_t max_carry_s);
 167
 168
 169 /**
 170  * Notify the tracker that a certain number of bytes of bandwidth have
 171  * been consumed.  Note that it is legal to consume bytes even if not
 172  * enough bandwidth is available (in that case,
 173  * GNUNET_BANDWIDTH_tracker_get_delay may return non-zero delay values
 174  * even for a size of zero for a while).
 175  *
 176  * @param av tracker to update
 177  * @param size number of bytes consumed
 178  * @return GNUNET_YES if this consumption is above the limit
 179  */
 180 int GNUNET_BANDWIDTH_tracker_consume (struct GNUNET_BANDWIDTH_Tracker *av,
 181                                       ssize_t size);
 182
 183
 184 /**
 185  * Compute how long we should wait until consuming 'size'
 186  * bytes of bandwidth in order to stay within the given
 187  * quota.
 188  *
 189  * @param av tracker to query
 190  * @param size number of bytes we would like to consume
 191  * @return time to wait for consumption to be OK
 192  */
 193 struct GNUNET_TIME_Relative GNUNET_BANDWIDTH_tracker_get_delay (struct
 194                                                                 GNUNET_BANDWIDTH_Tracker
 195                                                                 *av,
 196                                                                 size_t size);
 197
 198
 199 /**
 200  * Compute how many bytes are available for consumption right now.
 201  * quota.
 202  *
 203  * @param av tracker to query
 204  * @return number of bytes available for consumption right now
 205  */
 206 int64_t                  GNUNET_BANDWIDTH_tracker_get_available (struct
 207                                                                  GNUNET_BANDWIDTH_Tracker
 208                                                                  *av);
 209
 210
 211 /**
 212  * Update quota of bandwidth tracker.
 213  *
 214  * @param av tracker to initialize
 215  * @param bytes_per_second_limit new limit to assume
 216  */
 217 void GNUNET_BANDWIDTH_tracker_update_quota (struct GNUNET_BANDWIDTH_Tracker *av,
 218                                             struct GNUNET_BANDWIDTH_Value32NBO
 219                                             bytes_per_second_limit);
 220
 221
 222 #if 0                           /* keep Emacsens' auto-indent happy */
 223 {
 224 #endif
 225 #ifdef __cplusplus
 226 }
 227 #endif
 228
 229 /* ifndef GNUNET_BANDWIDTH_LIB_H */
 230 #endif
 231 /* end of gnunet_bandwidth_lib.h */