equalizer

package module
Version: v0.0.0-...-a959c50 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 16, 2021 License: MIT Imports: 7 Imported by: 0

README

equalizer

A rate limiters package for Go.

Pick one of the rate limiters to throttle requests and control quota.

Equalizer

Equalizer is a rate limiter that manages quota based on previous requests' statuses and slows down or accelerates accordingly.

Usage

offset := equalizer.NewRandomOffset(96)

// an Equalizer with the bitmap size of 96 with 16 reserved
// positive bits and the random offset manager
eq := equalizer.NewEqualizer(96, 16, offset)

// non-blocking quota request
haveQuota := eq.Ask()

// update with ten previous successful requests
eq.Notify(true, 10)

Benchmarks

BenchmarkEqualizerShortAskStep-16       30607452                37.5 ns/op             0 B/op          0 allocs/op
BenchmarkEqualizerShortAskRandom-16     31896340                34.5 ns/op             0 B/op          0 allocs/op
BenchmarkEqualizerShortNotify-16        12715494                81.9 ns/op             0 B/op          0 allocs/op
BenchmarkEqualizerLongAskStep-16        34627239                35.4 ns/op             0 B/op          0 allocs/op
BenchmarkEqualizerLongAskRandom-16      32399748                34.0 ns/op             0 B/op          0 allocs/op
BenchmarkEqualizerLongNotify-16            59935               20343 ns/op             0 B/op          0 allocs/op

Slider

Slider rate limiter is based on a sliding window with a specified quota capacity. Implements the Limiter interface.

Usage

// a Slider with one second window size, 100 millis sliding interval
// and the capacity of 32
slider := equalizer.NewSlider(time.Second, time.Millisecond*100, 32)

// non-blocking quota request
haveQuota := slider.Ask()

// blocking call
slider.Take()

Benchmarks

BenchmarkSliderShortWindow-16           123488035                9.67 ns/op            0 B/op          0 allocs/op
BenchmarkSliderLongerWindow-16          128023276                9.76 ns/op            0 B/op          0 allocs/op

TokenBucket

TokenBucket rate limiter is based on the token bucket algorithm with a refill interval. Implements the Limiter interface.

Usage

// a TokenBucket with the capacity of 32 and 100 millis refill interval
tokenBucket := equalizer.NewTokenBucket(32, time.Millisecond*100)

// non-blocking quota request
haveQuota := tokenBucket.Ask()

// blocking call
tokenBucket.Take()

Benchmarks

BenchmarkTokenBucketDenseRefill-16      212631714                5.64 ns/op            0 B/op          0 allocs/op
BenchmarkTokenBucketSparseRefill-16     211491368                5.63 ns/op            0 B/op          0 allocs/op

License

Licensed under the MIT License.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Equalizer

type Equalizer struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

An Equalizer represents a bitmap based adaptive rate limiter. The quota management algorithm is based on a Round-robin bitmap tape with a moving head.

An Equalizer is safe for use by multiple goroutines simultaneously.

Use Ask function to request quota. Use Notify to update the bitmap tape with previous requests' statuses.

func NewEqualizer

func NewEqualizer(size int, reserved int, offset Offset) *Equalizer

NewEqualizer allocates and returns a new Equalizer rate limiter.

len is the size of the bitmap. reserved is the number of reserved positive bits. offset is the equalizer.Offset strategy instance.

func (*Equalizer) Ask

func (eq *Equalizer) Ask() bool

Ask moves the tape head to the next index and returns the value.

func (*Equalizer) Notify

func (eq *Equalizer) Notify(value bool, n uint)

Notify shifts the tape left by n bits and appends the specified value n times. Use n > 1 to update the same value in a bulk to gain performance. value is the boolean representation of a bit value (false -> 0, true -> 1). n is the number of bits to set.

func (*Equalizer) Reset

func (eq *Equalizer) Reset()

Reset resets the tape to initial state.

func (*Equalizer) ResetPositive

func (eq *Equalizer) ResetPositive()

ResetPositive resets the tape with positive bits.

type Limiter

type Limiter interface {
	Ask() bool
	Take()
}

Limiter represents a rate limiter.

type Offset

type Offset interface {
	NextIndex() int
}

Offset is the Equalizer's tape offset manager interface.

type RandomOffset

type RandomOffset struct {
	Len int
}

RandomOffset is the random based offset manager.

func NewRandomOffset

func NewRandomOffset(len int) *RandomOffset

NewRandomOffset allocates and returns a new RandomOffset. len is the bitmap length.

func (*RandomOffset) NextIndex

func (ro *RandomOffset) NextIndex() int

NextIndex returns the next random index.

type Slider

type Slider struct {
	// contains filtered or unexported fields
}

A Slider represents a rate limiter which is based on a sliding window with a specified quota capacity. Implements the equalizer.Limiter interface.

A Slider is safe for use by multiple goroutines simultaneously.

The underlying slider instance ensures that the background goroutine does not keep the main Slider object from being garbage collected. When it is garbage collected, the finalizer stops the background goroutine, after which the underlying slider can be collected.

func NewSlider

func NewSlider(window time.Duration, slidingInterval time.Duration, capacity int) *Slider

NewSlider allocates and returns a new Slider rate limiter.

window is the fixed duration of the sliding window. slidingInterval controls how frequently a new sliding window is started. capacity is the quota limit for the window.

func (*Slider) Ask

func (s *Slider) Ask() bool

Ask requires a permit. It is a non blocking call, returns true or false.

func (*Slider) Take

func (s *Slider) Take()

Take blocks to get a permit.

type StepOffset

type StepOffset struct {
	Len  int
	Step int64
	// contains filtered or unexported fields
}

StepOffset is the step based offset manager.

func NewStepOffset

func NewStepOffset(len int, step int64) *StepOffset

NewStepOffset allocates and returns a new StepOffset. len is the bitmap length. step is the offset from the previous index.

func (*StepOffset) NextIndex

func (so *StepOffset) NextIndex() int

NextIndex returns the next index in the Round-robin way.

type TokenBucket

type TokenBucket struct {
	// contains filtered or unexported fields
}

A TokenBucket represents a rate limiter based on a custom implementation of the token bucket algorithm with a refill interval. Implements the equalizer.Limiter interface.

A TokenBucket is safe for use by multiple goroutines simultaneously.

The underlying tokenBucket instance ensures that the background goroutine does not keep the main TokenBucket object from being garbage collected. When it is garbage collected, the finalizer stops the background goroutine, after which the underlying tokenBucket can be collected.

func NewTokenBucket

func NewTokenBucket(capacity int32, refillInterval time.Duration) *TokenBucket

NewTokenBucket allocates and returns a new TokenBucket rate limiter.

capacity is the token bucket capacity. refillInterval is the bucket refill interval.

func (*TokenBucket) Ask

func (tb *TokenBucket) Ask() bool

Ask requires a permit. It is a non blocking call, returns true or false.

func (*TokenBucket) Take

func (tb *TokenBucket) Take()

Take blocks to get a permit.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL