tokenbucket

README

tokenbucket

Token bucket implementation in Go

Documentation

Index

• type TokenBucket
  • func (tb *TokenBucket) Adjust(delta Tokens)
  • func (tb *TokenBucket) Available() Tokens
  • func (tb *TokenBucket) Exhausted() time.Duration
  • func (tb *TokenBucket) Init(rate TokensPerSecond, burst Tokens)
  • func (tb *TokenBucket) InitWithNowFn(rate TokensPerSecond, burst Tokens, nowFn func() time.Time)
  • func (tb *TokenBucket) Reset()
  • func (tb *TokenBucket) TestingInternalParameters() (rate TokensPerSecond, burst, available Tokens)
  • func (tb *TokenBucket) TryToFulfill(amount Tokens) (fulfilled bool, tryAgainAfter time.Duration)
  • func (tb *TokenBucket) Update()
  • func (tb *TokenBucket) UpdateConfig(rate TokensPerSecond, burst Tokens)
  • func (tb *TokenBucket) Wait(amount Tokens)
  • func (tb *TokenBucket) WaitCtx(ctx context.Context, amount Tokens) error
• type Tokens
• type TokensPerSecond

Types

type TokenBucket

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

TokenBucket implements the basic accounting for a token bucket.

A token bucket has a rate of replenishment and a burst limit. Tokens are replenished over time, up to the burst limit.

The token bucket keeps track of the current amount and updates it as time passes. The bucket can go into debt (i.e. negative current amount).

func (*TokenBucket) Adjust

func (tb *TokenBucket) Adjust(delta Tokens)

Adjust returns tokens to the bucket (positive delta) or accounts for a debt of tokens (negative delta).

func (*TokenBucket) Available

func (tb *TokenBucket) Available() Tokens

Available returns the currently available tokens (can be -ve). Exported only for metrics.

func (*TokenBucket) Exhausted

func (tb *TokenBucket) Exhausted() time.Duration

Exhausted returns the cumulative duration over which this token bucket was exhausted. Exported only for metrics.

func (*TokenBucket) Init

func (tb *TokenBucket) Init(rate TokensPerSecond, burst Tokens)

Init the token bucket.

func (*TokenBucket) InitWithNowFn

func (tb *TokenBucket) InitWithNowFn(rate TokensPerSecond, burst Tokens, nowFn func() time.Time)

Init the token bucket with a custom "Now" function. Note that Wait/WaitCtx cannot be used with a custom time function.

func (*TokenBucket) Reset

func (tb *TokenBucket) Reset()

Reset resets the current tokens to whatever the burst is.

func (*TokenBucket) TestingInternalParameters

func (tb *TokenBucket) TestingInternalParameters() (rate TokensPerSecond, burst, available Tokens)

TestingInternalParameters returns the refill rate (configured), burst tokens (configured), and number of available tokens where available <= burst. It's used in tests.

func (*TokenBucket) TryToFulfill

func (tb *TokenBucket) TryToFulfill(amount Tokens) (fulfilled bool, tryAgainAfter time.Duration)

TryToFulfill either removes the given amount if is available, or returns a time after which the request should be retried.

func (*TokenBucket) Update

func (tb *TokenBucket) Update()

Update moves the time forward, accounting for the replenishment since the last update.

func (*TokenBucket) UpdateConfig

func (tb *TokenBucket) UpdateConfig(rate TokensPerSecond, burst Tokens)

UpdateConfig updates the rate and burst limits. The change in burst will be applied to the current token quantity. For example, if the RateLimiter currently had 5 available tokens and the burst is updated from 10 to 20, the amount will increase to 15. Similarly, if the burst is decreased by 10, the current quota will decrease accordingly, potentially putting the limiter into debt.

func (*TokenBucket) Wait

func (tb *TokenBucket) Wait(amount Tokens)

Wait removes the given amount, waiting as long as necessary.

func (*TokenBucket) WaitCtx

func (tb *TokenBucket) WaitCtx(ctx context.Context, amount Tokens) error

WaitCtx removes the given amount, waiting as long as necessary or until the context is canceled.

type Tokens

type Tokens float64

Tokens are abstract units (usually units of work).

type TokensPerSecond

type TokensPerSecond float64

TokensPerSecond is the rate of token replenishment.