Based on your examples, how can a client know how much time to wait until he can retry again?
boolean isThrottled = throttle.canProceed();
For example, if isThrottled returns true, I would like that the consumer pause until calling canProceed() again will likely receive false.
Thank for letting me know. That's a simple addition. I'll add it in. Probably by the end of the day.
One more thing, a little bit off-topic, but I won't open another issue: how do the three strategies implemented deal with the "burst-iness"? Meaning: do they allow bursts (excess) or no? If they allow, can it be made optional?
Neither of the strategies change the number of tokens based on burst-iness dynamics. Though you could chose one of the buckets that may closely fit a predefined requirement. The fixed token bucket is filled with the maximum available tokens at the beginning of the interval and does not limit you unless you exhaust them all with in the interval. The step down token bucket is generous initially but gradually gets stingy. ie. At the beginning of the interval you have all the tokens (max) available but at a fixed rate (step), the tokens are decreased. The actual value to which it would decrease at a step is the min(max tokens for the step, current available tokens). While the step up token bucket is the opposite of step down token bucket. It gets generous gradually over the course of the interval.
#7: Made change to code to include wait time.
* Added method waitTime() to Throttle.java
* Modified class names to reflect strategy.
I'v add a new method called waitTime(TimeUnit) to the Throttle class. This should help provide you some indication on when the next release will occur. If tokens are currently available, the wait time will be zero. Please not that I haven't written any unit tests for it yet. I will do that as soon as I can.
I have also added an example to the landing page.
Additionally I changed the names for some of the classes to *TokenBucketStrategy to better describe them.
Thanks for update, I will take look today. Meanwhile, I have done a .NET port of your library. I hope you are ok with this and I have you permission to publish it (you don't mention any licensing conditions in your repo). While is not fully ready (docs needs to be improved and create the tests for Leaky bucket strategies), I believe it is functional.
You can find the repo at: https://github.com/robertmircea/RateLimiters
No problem, go for it. I'll explore licensing as well. And thanks for the reference.
fixed #7: Added unit tests for wait time to next release feature
#7: Fixed race condition in test.