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