rate

README

Lockfree version of the golang.org/x/time/rate.Limiter struct

This package provides a token bucket rate limiter supporting a subset of the rate.Limiter API that is up to 100x faster under contention. To accomplish this we only support the Allow() method.

While performance of the original Limiter degraded under contention, this version scales linearly to at least 8 cores:

$ benchstat old.txt new.txt
name      old time/op    new time/op    delta
AllowN      32.3ns ± 0%     3.4ns ± 0%  -89.41%  (p=0.002 n=6+6)
AllowN-2    84.0ns ± 1%     1.8ns ± 0%  -97.90%  (p=0.002 n=6+6)
AllowN-4     126ns ± 3%       1ns ± 0%  -99.28%  (p=0.004 n=5+6)
AllowN-8     136ns ± 1%       0ns ± 0%  -99.66%  (p=0.004 n=5+6)

Documentation

Overview

Package rate provides a rate limiter.

Index

• Constants
• type Limit
  • func Every(interval time.Duration) Limit
• type Limiter
  • func NewLimiter(r Limit, b int) *Limiter
  • func (lim *Limiter) Allow() bool
  • func (lim *Limiter) Burst() int
  • func (lim *Limiter) Limit() Limit

Constants

const Inf = Limit(math.MaxFloat64)

Inf is the infinite rate limit; it allows all events (even if burst is zero).

const InfDuration = time.Duration(1<<63 - 1)

InfDuration is the duration returned by Delay when a Reservation is not OK.

Types

type Limit

type Limit float64

Limit defines the maximum frequency of some events. Limit is represented as number of events per second. A zero Limit allows no events.

func Every

func Every(interval time.Duration) Limit

Every converts a minimum time interval between events to a Limit.

type Limiter

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

A Limiter controls how frequently events are allowed to happen. It implements a "token bucket" of size b, initially full and refilled at rate r tokens per second. Informally, in any large enough time interval, the Limiter limits the rate to r tokens per second, with a maximum burst size of b events. As a special case, if r == Inf (the infinite rate), b is ignored. See https://en.wikipedia.org/wiki/Token_bucket for more about token buckets.

The zero value is a valid Limiter, but it will reject all events. Use NewLimiter to create non-zero Limiters.

Limiter has one main methods, Allow. Allow consumes a single token. If no token is available, Allow returns false.

func NewLimiter

func NewLimiter(r Limit, b int) *Limiter

NewLimiter returns a new Limiter that allows events up to rate r and permits bursts of at most b tokens. NOTE: the maximum burst we can represent is a little over 100k tokens; bursts greater than that will be truncated.

func (*Limiter) Allow

func (lim *Limiter) Allow() bool

Allow returns true if there was an available token in the limiter.

func (*Limiter) Burst

func (lim *Limiter) Burst() int

Burst returns the maximum burst size. Burst is the maximum number of tokens that can be consumed in a single call to Allow, so higher Burst values allow more events to happen at once. A zero Burst allows no events, unless limit == Inf.

func (*Limiter) Limit

func (lim *Limiter) Limit() Limit

Limit returns the maximum overall event rate.