The equalizer package provides a set of simple and easy-to-use rate limiters for Go. These rate limiters can be used to limit the rate of requests to any resource, such as a database, API, or file.

The package includes the following rate limiters:

• Equalizer
• Slider
• Token Bucket

Equalizer is a rate limiter that adjusts the rate of requests based on the outcomes of previous requests. If previous attempts have failed, Equalizer will slow down the rate of requests to avoid overloading the system. Conversely, if previous attempts have been successful, Equalizer will accelerate the rate of requests to make the most of the available capacity.

// a random offset manager 
offset := equalizer.NewRandomOffset(96)
// an Equalizer with a bitmap size of 96, 16 reserved positive bits, and the random offset manager
eq := equalizer.NewEqualizer(96, 16, offset)
// non-blocking quota request
haveQuota := eq.TryAcquire()
// update on the successful request
eq.Success(1)

BenchmarkEqualizer_ShortTryAcquireStep-16       31538967                38.33 ns/op            0 B/op          0 allocs/op
BenchmarkEqualizer_ShortTryAcquireRandom-16     37563639                31.66 ns/op            0 B/op          0 allocs/op
BenchmarkEqualizer_ShortNotify-16               29519719                40.43 ns/op            0 B/op          0 allocs/op
BenchmarkEqualizer_LongTryAcquireStep-16        32084402                38.36 ns/op            0 B/op          0 allocs/op
BenchmarkEqualizer_LongTryAcquireRandom-16      39996501                30.37 ns/op            0 B/op          0 allocs/op
BenchmarkEqualizer_LongNotify-16                29648655                40.46 ns/op            0 B/op          0 allocs/op

Slider tracks the number of requests that have been processed in a recent time window. If the number of requests exceeds the limit, the rate limiter will block new requests until the window has moved forward. Implements the equalizer.Limiter interface.

// a Slider with a one-second window size, a 100-millisecond sliding interval,
// and a capacity of 32
slider := equalizer.NewSlider(time.Second, 100*time.Millisecond, 32)
// non-blocking quota request
haveQuota := slider.TryAcquire()
// blocking call
slider.Acquire(context.Background())

BenchmarkSlider_TryAcquire-16                   293645348                4.033 ns/op           0 B/op          0 allocs/op
BenchmarkRateLimiter_Allow-16                     9362382              127.4 ns/op             0 B/op          0 allocs/op

^* Compared to rate.Limiter from the golang.org/x/time package.

TokenBucket maintains a fixed number of tokens. Each token represents a request that can be processed. When a request is made, the rate limiter checks to see if there are any available tokens. If there are, the request is processed and one token is removed from the bucket. If there are no available tokens, the request is blocked until a token becomes available. Implements the equalizer.Limiter interface.

// a TokenBucket with the capacity of 32 and a 100-millisecond refill interval
tokenBucket := equalizer.NewTokenBucket(32, 100*time.Millisecond)
// non-blocking quota request
haveQuota := tokenBucket.TryAcquire()
// blocking call
tokenBucket.Acquire(context.Background())

BenchmarkTokenBucket_TryAcquire-16              304653043                3.909 ns/op           0 B/op          0 allocs/op
BenchmarkRateLimiter_Allow-16                     9362382              127.4 ns/op             0 B/op          0 allocs/op

^* Compared to rate.Limiter from the golang.org/x/time package.

Licensed under the MIT License.