GoogleCodeExporter
commented
9 years ago We didn't invest the time to do an API review on this. E.g. finding an
agreeable method name, and argument names (I recall I had trouble writing the
javadoc for explaining the arguments).
* @param permitsPerSecond the rate of the returned {@code RateLimiter}, measured in
* how many permits become available per second. Must be positive
* @param maxBurstBuildup the maximum period of time where unused permits are accumulated by the
* rate limiter, that can later be handed out with no wait time
* @param unit the time unit of the maxBurstBuildup argument
*/
public static RateLimiter createWithCapacity(
double permitsPerSecond, long maxBurstBuildup, TimeUnit unit)
As you can see, especially "maxBurstBuildup" is awkward to describe. It
specifies it as a quantity of time, not permits (in the sense "maximum burst of
10 permits"), because then its meaning remains invariant even if the user calls
setRate() and switch to a different rate limit.
This allows, for example, the default implementation to always produce a
maximum burst of "1 second-worth-of-permits" (the permits that a RateLimiter
would produce in a single second, e.g. if the rate is 10qps, then this is a
burst of "10 permits"), i.e. something that should be tiny, no matter what the
rate limit is.
Another option would be to say, "screw this, let's describe bursts as
maxPermits" (this is simpler to explain), and add a warning of the sort, "if
you call setRate(...), then the relative size of the burst (in relation to the
rate limit) changes".
E.g., a maxBurst of "100 permits" for a rate limit of 0.01qps, would imply that
the RateLimiter could allow in a burst the throughput that would otherwise need
almost three hours to go through. If the rate limit is 100qps, then this burst
would merely allow in a burst the throughput of that would take one second.
So it's a choice between a burst description that remains invariant in terms of
time, and a burst description that remains invariant in terms of permits. I
thought the first is more useful (to be able to describe "small" and "big"
bursts, without even knowing the rate), but the second is certainly easier to
describe and understand. Original comment by andr...@google.com on 26 Mar 2014 at 5:51
Original issue reported on code.google.com by
kak@google.comon 26 Mar 2014 at 4:28