Equalizer

<h1 align="center">equalizer</h1> <p align="center"> <a href="https://github.com/reugn/equalizer/actions/workflows/build.yml"><img src="https://github.com/reugn/equalizer/actions/workflows/build.yml/badge.svg"></a> <a href="https://pkg.go.dev/github.com/reugn/equalizer"><img src="https://pkg.go.dev/badge/github.com/reugn/equalizer"></a> <a href="https://goreportcard.com/report/github.com/reugn/equalizer"><img src="https://goreportcard.com/badge/github.com/reugn/equalizer"></a> <a href="https://codecov.io/gh/reugn/equalizer"><img src="https://codecov.io/gh/reugn/equalizer/branch/master/graph/badge.svg"></a> </p>

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

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.

Usage Example

// 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)

Benchmarks

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

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.

Usage Example

// 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())

Benchmarks

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.

Token Bucket

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.

Usage Example

// 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())

Benchmarks

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.

License

Licensed under the MIT License.