ratelimit

package module
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2019 License: LGPL-3.0 Imports: 6 Imported by: 10

README

ratelimit

-- import "github.com/juju/ratelimit"

The ratelimit package provides an efficient token bucket implementation. See http://en.wikipedia.org/wiki/Token_bucket.

Usage

func Reader
func Reader(r io.Reader, bucket *Bucket) io.Reader

Reader returns a reader that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func Writer
func Writer(w io.Writer, bucket *Bucket) io.Writer

Writer returns a writer that is rate limited by the given token bucket. Each token in the bucket represents one byte.

type Bucket
type Bucket struct {
}

Bucket represents a token bucket that fills at a predetermined rate. Methods on Bucket may be called concurrently.

func NewBucket
func NewBucket(fillInterval time.Duration, capacity int64) *Bucket

NewBucket returns a new token bucket that fills at the rate of one token every fillInterval, up to the given maximum capacity. Both arguments must be positive. The bucket is initially full.

func NewBucketWithQuantum
func NewBucketWithQuantum(fillInterval time.Duration, capacity, quantum int64) *Bucket

NewBucketWithQuantum is similar to NewBucket, but allows the specification of the quantum size - quantum tokens are added every fillInterval.

func NewBucketWithRate
func NewBucketWithRate(rate float64, capacity int64) *Bucket

NewBucketWithRate returns a token bucket that fills the bucket at the rate of rate tokens per second up to the given maximum capacity. Because of limited clock resolution, at high rates, the actual rate may be up to 1% different from the specified rate.

func (*Bucket) Available
func (tb *Bucket) Available() int64

Available returns the number of available tokens. It will be negative when there are consumers waiting for tokens. Note that if this returns greater than zero, it does not guarantee that calls that take tokens from the buffer will succeed, as the number of available tokens could have changed in the meantime. This method is intended primarily for metrics reporting and debugging.

func (*Bucket) Rate
func (tb *Bucket) Rate() float64

Rate returns the fill rate of the bucket, in tokens per second.

func (*Bucket) Take
func (tb *Bucket) Take(count int64) time.Duration

Take takes count tokens from the bucket without blocking. It returns the time that the caller should wait until the tokens are actually available.

Note that if the request is irrevocable - there is no way to return tokens to the bucket once this method commits us to taking them.

func (*Bucket) TakeAvailable
func (tb *Bucket) TakeAvailable(count int64) int64

TakeAvailable takes up to count immediately available tokens from the bucket. It returns the number of tokens removed, or zero if there are no available tokens. It does not block.

func (*Bucket) TakeMaxDuration
func (tb *Bucket) TakeMaxDuration(count int64, maxWait time.Duration) (time.Duration, bool)

TakeMaxDuration is like Take, except that it will only take tokens from the bucket if the wait time for the tokens is no greater than maxWait.

If it would take longer than maxWait for the tokens to become available, it does nothing and reports false, otherwise it returns the time that the caller should wait until the tokens are actually available, and reports true.

func (*Bucket) Wait
func (tb *Bucket) Wait(count int64)

Wait takes count tokens from the bucket, waiting until they are available.

func (*Bucket) WaitMaxDuration
func (tb *Bucket) WaitMaxDuration(count int64, maxWait time.Duration) bool

WaitMaxDuration is like Wait except that it will only take tokens from the bucket if it needs to wait for no greater than maxWait. It reports whether any tokens have been removed from the bucket If no tokens have been removed, it returns immediately.

Documentation

Overview

Package ratelimit provides an efficient token bucket implementation that can be used to limit the rate of arbitrary things. See http://en.wikipedia.org/wiki/Token_bucket.

Index

Constants

View Source 
const (
	FieldFillInterval = iota
	FieldCapacity
	FieldQuantum
)

Variables

This section is empty.

Functions

func NewReadCloser 

func NewReadCloser(r io.ReadCloser, bucket Bucket) io.ReadCloser

NewReader returns a readCloser that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func NewReadSeeker 

func NewReadSeeker(r io.ReadSeeker, bucket Bucket) io.ReadSeeker

NewReader returns a readSeeker that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func NewReader 

func NewReader(r io.Reader, bucket Bucket) io.Reader

NewReader returns a reader that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func NewWriteCloser 

func NewWriteCloser(w io.WriteCloser, bucket Bucket) io.WriteCloser

NewWriter returns a writer that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func NewWriteSeeker 

func NewWriteSeeker(w io.WriteSeeker, bucket Bucket) io.WriteSeeker

NewWriter returns a writer that is rate limited by the given token bucket. Each token in the bucket represents one byte.

func NewWriter 

func NewWriter(w io.Writer, bucket Bucket) io.Writer

NewWriter returns a writer that is rate limited by the given token bucket. Each token in the bucket represents one byte.

Types

type Bucket 

type Bucket interface {
	Wait(count int64)
	WaitMaxDuration(count int64, maxWait time.Duration) bool
	Take(count int64) time.Duration
	TakeMaxDuration(count int64, maxWait time.Duration) (time.Duration, bool)
	TakeAvailable(count int64) int64
	Available() int64
	Capacity() int64
	Rate() float64
}

type FakeBucket 

type FakeBucket struct{}

func NewFakeBucket 

func NewFakeBucket() *FakeBucket

NewBucket returns a new fake token bucket.

func (*FakeBucket) Available 

func (tb *FakeBucket) Available() int64

Available returns the number of available tokens.

func (*FakeBucket) Capacity 

func (tb *FakeBucket) Capacity() int64

Capacity returns the capacity that the bucket was created with.

func (*FakeBucket) Rate 

func (tb *FakeBucket) Rate() float64

Rate returns the fill rate of the bucket, in tokens per second.

func (*FakeBucket) Take 

func (tb *FakeBucket) Take(count int64) time.Duration

Take takes count tokens from the bucket without blocking. It returns the time that the caller should wait until the tokens are actually available.

Note that if the request is irrevocable - there is no way to return tokens to the bucket once this method commits us to taking them.

func (*FakeBucket) TakeAvailable 

func (tb *FakeBucket) TakeAvailable(count int64) int64

TakeAvailable takes up to count immediately available tokens from the bucket. It returns the number of tokens removed, or zero if there are no available tokens. It does not block.

func (*FakeBucket) TakeMaxDuration 

func (tb *FakeBucket) TakeMaxDuration(count int64, maxWait time.Duration) (time.Duration, bool)

TakeMaxDuration is like Take, except that it will only take tokens from the bucket if the wait time for the tokens is no greater than maxWait.

If it would take longer than maxWait for the tokens to become available, it does nothing and reports false, otherwise it returns the time that the caller should wait until the tokens are actually available, and reports true.

func (*FakeBucket) Wait 

func (tb *FakeBucket) Wait(count int64)

Wait takes count tokens from the bucket, waiting until they are available.

func (*FakeBucket) WaitMaxDuration 

func (tb *FakeBucket) WaitMaxDuration(count int64, maxWait time.Duration) bool

WaitMaxDuration is like Wait.

type Field 

type Field int

type QuantumError 

type QuantumError struct {
	Rate float64
}

func (*QuantumError) Error 

func (e *QuantumError) Error() string

type RealBucket 

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

RealBucket represents a token bucket that fills at a predetermined rate. Methods on RealBucket may be called concurrently.

func NewBucket 

func NewBucket(fillInterval time.Duration, capacity int64) (*RealBucket, error)

NewBucket returns a new token bucket that fills at the rate of one token every fillInterval, up to the given maximum capacity. Both arguments must be positive. The bucket is initially full.

func NewBucketWithQuantum 

func NewBucketWithQuantum(fillInterval time.Duration, capacity, quantum int64) (*RealBucket, error)

NewBucketWithQuantum is similar to NewBucket, but allows the specification of the quantum size - quantum tokens are added every fillInterval.

func NewBucketWithRate 

func NewBucketWithRate(rate float64, capacity int64) (*RealBucket, error)

NewBucketWithRate returns a token bucket that fills the bucket at the rate of rate tokens per second up to the given maximum capacity. Because of limited clock resolution, at high rates, the actual rate may be up to 1% different from the specified rate.

func (*RealBucket) Available 

func (tb *RealBucket) Available() int64

Available returns the number of available tokens. It will be negative when there are consumers waiting for tokens. Note that if this returns greater than zero, it does not guarantee that calls that take tokens from the buffer will succeed, as the number of available tokens could have changed in the meantime. This method is intended primarily for metrics reporting and debugging.

func (*RealBucket) Capacity 

func (tb *RealBucket) Capacity() int64

Capacity returns the capacity that the bucket was created with.

func (*RealBucket) Rate 

func (tb *RealBucket) Rate() float64

Rate returns the fill rate of the bucket, in tokens per second.

func (*RealBucket) Take 

func (tb *RealBucket) Take(count int64) time.Duration

Take takes count tokens from the bucket without blocking. It returns the time that the caller should wait until the tokens are actually available.

Note that if the request is irrevocable - there is no way to return tokens to the bucket once this method commits us to taking them.

func (*RealBucket) TakeAvailable 

func (tb *RealBucket) TakeAvailable(count int64) int64

TakeAvailable takes up to count immediately available tokens from the bucket. It returns the number of tokens removed, or zero if there are no available tokens. It does not block.

func (*RealBucket) TakeMaxDuration 

func (tb *RealBucket) TakeMaxDuration(count int64, maxWait time.Duration) (time.Duration, bool)

TakeMaxDuration is like Take, except that it will only take tokens from the bucket if the wait time for the tokens is no greater than maxWait.

If it would take longer than maxWait for the tokens to become available, it does nothing and reports false, otherwise it returns the time that the caller should wait until the tokens are actually available, and reports true.

func (*RealBucket) Wait 

func (tb *RealBucket) Wait(count int64)

Wait takes count tokens from the bucket, waiting until they are available.

func (*RealBucket) WaitMaxDuration 

func (tb *RealBucket) WaitMaxDuration(count int64, maxWait time.Duration) bool

WaitMaxDuration is like Wait except that it will only take tokens from the bucket if it needs to wait for no greater than maxWait. It reports whether any tokens have been removed from the bucket If no tokens have been removed, it returns immediately.

type ValueError 

type ValueError struct {
	Field Field
	Value int64
}

func (*ValueError) Error 

func (e *ValueError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.