Starting with a full bucket

[grr]

Algorithm::TokenBucket always starts with an empty bucket, so processing will always start with a delay. That's not immediately apparent unless you're familiar with the algorithm details. It would be nice if you could specify in the constructor to start with a full bucket. An undocumented way to do this is to call count with a negative token count. Looking at other implementations in other languages, this is not an uncommon desire. In fact some implementations default to starting with a full bucket (like golang.org/x/time/rate).

Also, after looking at the example in the docs using 2 rate limiters together, it might be convenient to make until smarter to deal with multiple buckets, e.g. $rl1->until(1, $rl2, ...). And internally it would compute max($rl1->until(1), $rl2->until(1), ...).

[grr]

Turns out this is just a documentation issue. The constructor states:

It can also take the current token counter and last check time but this usage is mostly intended for restoring a saved bucket.

So I didn't notice I could just pass in the same value as burst size for current token counter and start with a full bucket. A single sentence in the doc for new would resolve this. And maybe another sentence in the description to indicate the difference between starting with an empty and full bucket.