2 This file is part of GNUnet.
3 Copyright (C) 2010 Christian Grothoff (and other contributing authors)
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.
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.
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.
22 * @file include/gnunet_bandwidth_lib.h
23 * @brief functions related to bandwidth (unit)
24 * @author Christian Grothoff
27 #ifndef GNUNET_BANDWIDTH_LIB_H
28 #define GNUNET_BANDWIDTH_LIB_H
33 #if 0 /* keep Emacsens' auto-indent happy */
38 #include "gnunet_common.h"
39 #include "gnunet_time_lib.h"
41 GNUNET_NETWORK_STRUCT_BEGIN
44 * 32-bit bandwidth used for network exchange by GNUnet, in bytes per second.
46 struct GNUNET_BANDWIDTH_Value32NBO
49 * The actual value (bytes per second).
51 uint32_t value__ GNUNET_PACKED;
53 GNUNET_NETWORK_STRUCT_END
57 * Callback to be called by the bandwidth tracker if the tracker
58 * was updated and the client should update it's delay values
60 * @param cls a closure to pass
63 (*GNUNET_BANDWIDTH_TrackerUpdateCallback) (void *cls);
67 * Callback to be called by the bandwidth tracker if the tracker
68 * was updated and the client should update it's delay values
70 * @param cls a closure to pass
73 (*GNUNET_BANDWIDTH_ExcessNotificationCallback) (void *cls);
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 '__').
83 struct GNUNET_BANDWIDTH_Tracker
86 * Closure for @e update_cb.
91 * Function we call if the tracker's bandwidth is increased and a
92 * previously returned timeout might now expire earlier.
94 GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb;
97 * Closure for @e excess_cb.
102 * Function we call if the tracker is about to throw
103 * away bandwidth due to excess (max carry exceeded).
105 GNUNET_BANDWIDTH_ExcessNotificationCallback excess_cb;
108 * Number of bytes consumed since we last updated the tracker.
110 int64_t consumption_since_last_update__;
113 * Task scheduled to call the @e excess_cb once we have
114 * reached the maximum bandwidth the tracker can hold.
116 struct GNUNET_SCHEDULER_Task * excess_task;
119 * Time when we last updated the tracker.
121 struct GNUNET_TIME_Absolute last_update__;
124 * Bandwidth limit to enforce in bytes per s.
126 uint32_t available_bytes_per_s__;
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.
133 uint32_t max_carry_s__;
138 * Convenience definition to use for 0-bandwidth.
140 #define GNUNET_BANDWIDTH_ZERO GNUNET_BANDWIDTH_value_init (0)
144 * Create a new bandwidth value.
146 * @param bytes_per_second value to create
147 * @return the new bandwidth value
149 struct GNUNET_BANDWIDTH_Value32NBO
150 GNUNET_BANDWIDTH_value_init (uint32_t bytes_per_second);
154 * Maximum possible bandwidth value.
156 #define GNUNET_BANDWIDTH_VALUE_MAX GNUNET_BANDWIDTH_value_init(UINT32_MAX)
160 * At the given bandwidth, calculate how much traffic will be
161 * available until the given deadline.
163 * @param bps bandwidth
164 * @param deadline when is the deadline
165 * @return number of bytes available at bps until deadline
168 GNUNET_BANDWIDTH_value_get_available_until (struct GNUNET_BANDWIDTH_Value32NBO bps,
169 struct GNUNET_TIME_Relative deadline);
173 * At the given bandwidth, calculate how long it would take for
174 * 'size' bytes to be transmitted.
176 * @param bps bandwidth
177 * @param size number of bytes we want to have available
178 * @return how long it would take
180 struct GNUNET_TIME_Relative
181 GNUNET_BANDWIDTH_value_get_delay_for (struct GNUNET_BANDWIDTH_Value32NBO bps,
186 * Compute the MIN of two bandwidth values.
188 * @param b1 first value
189 * @param b2 second value
190 * @return the min of b1 and b2
192 struct GNUNET_BANDWIDTH_Value32NBO
193 GNUNET_BANDWIDTH_value_min (struct GNUNET_BANDWIDTH_Value32NBO b1,
194 struct GNUNET_BANDWIDTH_Value32NBO b2);
198 * Compute the MAX of two bandwidth values.
200 * @param b1 first value
201 * @param b2 second value
202 * @return the min of b1 and b2
204 struct GNUNET_BANDWIDTH_Value32NBO
205 GNUNET_BANDWIDTH_value_max (struct GNUNET_BANDWIDTH_Value32NBO b1,
206 struct GNUNET_BANDWIDTH_Value32NBO b2);
210 * Initialize bandwidth tracker. Note that in addition to the
211 * 'max_carry_s' limit, we also always allow at least
212 * #GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate. So if the
213 * bytes-per-second limit is so small that within 'max_carry_s' not
214 * even #GNUNET_SERVER_MAX_MESSAGE_SIZE is allowed to accumulate, it is
215 * ignored and replaced by #GNUNET_SERVER_MAX_MESSAGE_SIZE (which is in
218 * @param av tracker to initialize
219 * @param update_cb callback to notify a client about the tracker being updated
220 * @param update_cb_cls cls for the @a update_cb callback
221 * @param bytes_per_second_limit initial limit to assume
222 * @param max_carry_s maximum number of seconds unused bandwidth
223 * may accumulate before it expires
226 GNUNET_BANDWIDTH_tracker_init (struct GNUNET_BANDWIDTH_Tracker *av,
227 GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb,
229 struct GNUNET_BANDWIDTH_Value32NBO bytes_per_second_limit,
230 uint32_t max_carry_s);
234 * Initialize bandwidth tracker. Note that in addition to the
235 * 'max_carry_s' limit, we also always allow at least
236 * GNUNET_SERVER_MAX_MESSAGE_SIZE to accumulate. So if the
237 * bytes-per-second limit is so small that within 'max_carry_s' not
238 * even GNUNET_SERVER_MAX_MESSAGE_SIZE is allowed to accumulate, it is
239 * ignored and replaced by GNUNET_SERVER_MAX_MESSAGE_SIZE (which is in
242 * @param av tracker to initialize
243 * @param update_cb callback to notify a client about the tracker being updated
244 * @param update_cb_cls cls for the @a update_cb callback
245 * @param bytes_per_second_limit initial limit to assume
246 * @param max_carry_s maximum number of seconds unused bandwidth
247 * may accumulate before it expires
248 * @param excess_cb callback to notify if we have excess bandwidth
249 * @param excess_cb_cls closure for @a excess_cb
252 GNUNET_BANDWIDTH_tracker_init2 (struct GNUNET_BANDWIDTH_Tracker *av,
253 GNUNET_BANDWIDTH_TrackerUpdateCallback update_cb,
255 struct GNUNET_BANDWIDTH_Value32NBO bytes_per_second_limit,
256 uint32_t max_carry_s,
257 GNUNET_BANDWIDTH_ExcessNotificationCallback excess_cb,
258 void *excess_cb_cls);
262 * Stop notifying about tracker updates and excess notifications
264 * @param av the respective trackers
267 GNUNET_BANDWIDTH_tracker_notification_stop (struct GNUNET_BANDWIDTH_Tracker *av);
271 * Notify the tracker that a certain number of bytes of bandwidth have
272 * been consumed. Note that it is legal to consume bytes even if not
273 * enough bandwidth is available (in that case,
274 * #GNUNET_BANDWIDTH_tracker_get_delay() may return non-zero delay values
275 * even for a size of zero for a while).
277 * @param av tracker to update
278 * @param size number of bytes consumed
279 * @return #GNUNET_YES if this consumption is above the limit
282 GNUNET_BANDWIDTH_tracker_consume (struct GNUNET_BANDWIDTH_Tracker *av,
287 * Compute how long we should wait until consuming 'size'
288 * bytes of bandwidth in order to stay within the given
291 * @param av tracker to query
292 * @param size number of bytes we would like to consume
293 * @return time to wait for consumption to be OK
295 struct GNUNET_TIME_Relative
296 GNUNET_BANDWIDTH_tracker_get_delay (struct GNUNET_BANDWIDTH_Tracker *av,
301 * Compute how many bytes are available for consumption right now.
304 * @param av tracker to query
305 * @return number of bytes available for consumption right now
308 GNUNET_BANDWIDTH_tracker_get_available (struct GNUNET_BANDWIDTH_Tracker *av);
312 * Update quota of bandwidth tracker.
314 * @param av tracker to initialize
315 * @param bytes_per_second_limit new limit to assume
318 GNUNET_BANDWIDTH_tracker_update_quota (struct GNUNET_BANDWIDTH_Tracker *av,
319 struct GNUNET_BANDWIDTH_Value32NBO
320 bytes_per_second_limit);
323 #if 0 /* keep Emacsens' auto-indent happy */
330 /* ifndef GNUNET_BANDWIDTH_LIB_H */
332 /* end of gnunet_bandwidth_lib.h */