tokenbucket

README

[![GoDoc](http://godoc.org/github.com/ChimeraCoder/tokenbucket?status.png)](http://godoc.org/github.com/ChimeraCoder/tokenbucket)

tokenbucket
====================

This package provides an implementation of [Token bucket](https://en.wikipedia.org/wiki/Token_bucket) scheduling in Go. It is useful for implementing rate-limiting, traffic shaping, or other sorts of scheduling that depend on bandwidth constraints.


Example
------------


To create a new bucket, specify a capacity (how many tokens can be stored "in the bank"), and a rate (how often a new token is added).

````go

    // Create a new bucket
	// Allow a new action every 5 seconds, with a maximum of 3 "in the bank"
	bucket := tokenbucket.NewBucket(3, 5 * time.Second)
````

This bucket should be shared between any functions that share the same constraints. (These functions may or may not run in separate goroutines).


Anytime a regulated action is performed, spend a token.

````go
	// To perform a regulated action, we must spend a token
	// RegulatedAction will not be performed until the bucket contains enough tokens
	<-bucket.SpendToken(1)
	RegulatedAction()
````

`SpendToken` returns immediately. Reading from the channel that it returns will block until the action has "permission" to continue (ie, until there are enough tokens in the bucket).


(The channel that `SpendToken` returns is of type `error`. For now, the value will always be `nil`, so it can be ignored.)



####License

`tokenbucket` is free software provided under version 3 of the LGPL license.


Software that uses `tokenbucket` may be released under *any* license, as long as the source code for `tokenbucket` (including any modifications) are made available under the LGPLv3 license.

You do not need to release the rest of the software under the LGPL, or any free/open-source license, for that matter (though we would encourage you to do so!).

Documentation

Index

• type Bucket
  • func NewBucket(rate time.Duration, capacity int64) *Bucket
  • func (b *Bucket) AddToken(n int64)
  • func (b *Bucket) Drain() error
  • func (b *Bucket) GetRate() time.Duration
  • func (b *Bucket) SetRate(rate time.Duration)
  • func (b *Bucket) SpendToken(n int64) <-chan error

Types

type Bucket

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

func NewBucket

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

func (*Bucket) AddToken

func (b *Bucket) AddToken(n int64)

AddTokens manually adds n tokens to the bucket

func (*Bucket) Drain

func (b *Bucket) Drain() error

Drain will empty all tokens in the bucket If the tokens are being added too quickly (if the rate is too fast) this will never drain

func (*Bucket) GetRate

func (b *Bucket) GetRate() time.Duration

func (*Bucket) SetRate

func (b *Bucket) SetRate(rate time.Duration)

func (*Bucket) SpendToken

func (b *Bucket) SpendToken(n int64) <-chan error