github.com/lrita/ratelimit@v0.0.0-20190723030019-81504bd89bc5/README.md (about) 1 # ratelimit 2 -- 3 import "github.com/juju/ratelimit" 4 5 The ratelimit package provides an efficient token bucket implementation. See 6 http://en.wikipedia.org/wiki/Token_bucket. 7 8 ## Usage 9 10 #### func Reader 11 12 ```go 13 func Reader(r io.Reader, bucket *Bucket) io.Reader 14 ``` 15 Reader returns a reader that is rate limited by the given token bucket. Each 16 token in the bucket represents one byte. 17 18 #### func Writer 19 20 ```go 21 func Writer(w io.Writer, bucket *Bucket) io.Writer 22 ``` 23 Writer returns a writer that is rate limited by the given token bucket. Each 24 token in the bucket represents one byte. 25 26 #### type Bucket 27 28 ```go 29 type Bucket struct { 30 } 31 ``` 32 33 Bucket represents a token bucket that fills at a predetermined rate. Methods on 34 Bucket may be called concurrently. 35 36 #### func NewBucket 37 38 ```go 39 func NewBucket(fillInterval time.Duration, capacity int64) *Bucket 40 ``` 41 NewBucket returns a new token bucket that fills at the rate of one token every 42 fillInterval, up to the given maximum capacity. Both arguments must be positive. 43 The bucket is initially full. 44 45 #### func NewBucketWithQuantum 46 47 ```go 48 func NewBucketWithQuantum(fillInterval time.Duration, capacity, quantum int64) *Bucket 49 ``` 50 NewBucketWithQuantum is similar to NewBucket, but allows the specification of 51 the quantum size - quantum tokens are added every fillInterval. 52 53 #### func NewBucketWithRate 54 55 ```go 56 func NewBucketWithRate(rate float64, capacity int64) *Bucket 57 ``` 58 NewBucketWithRate returns a token bucket that fills the bucket at the rate of 59 rate tokens per second up to the given maximum capacity. Because of limited 60 clock resolution, at high rates, the actual rate may be up to 1% different from 61 the specified rate. 62 63 #### func (*Bucket) Rate 64 65 ```go 66 func (tb *Bucket) Rate() float64 67 ``` 68 Rate returns the fill rate of the bucket, in tokens per second. 69 70 #### func (*Bucket) Take 71 72 ```go 73 func (tb *Bucket) Take(count int64) time.Duration 74 ``` 75 Take takes count tokens from the bucket without blocking. It returns the time 76 that the caller should wait until the tokens are actually available. 77 78 Note that if the request is irrevocable - there is no way to return tokens to 79 the bucket once this method commits us to taking them. 80 81 #### func (*Bucket) TakeAvailable 82 83 ```go 84 func (tb *Bucket) TakeAvailable(count int64) int64 85 ``` 86 TakeAvailable takes up to count immediately available tokens from the bucket. It 87 returns the number of tokens removed, or zero if there are no available tokens. 88 It does not block. 89 90 #### func (*Bucket) TakeMaxDuration 91 92 ```go 93 func (tb *Bucket) TakeMaxDuration(count int64, maxWait time.Duration) (time.Duration, bool) 94 ``` 95 TakeMaxDuration is like Take, except that it will only take tokens from the 96 bucket if the wait time for the tokens is no greater than maxWait. 97 98 If it would take longer than maxWait for the tokens to become available, it does 99 nothing and reports false, otherwise it returns the time that the caller should 100 wait until the tokens are actually available, and reports true. 101 102 #### func (*Bucket) Wait 103 104 ```go 105 func (tb *Bucket) Wait(count int64) 106 ``` 107 Wait takes count tokens from the bucket, waiting until they are available. 108 109 #### func (*Bucket) WaitMaxDuration 110 111 ```go 112 func (tb *Bucket) WaitMaxDuration(count int64, maxWait time.Duration) bool 113 ``` 114 WaitMaxDuration is like Wait except that it will only take tokens from the 115 bucket if it needs to wait for no greater than maxWait. It reports whether any 116 tokens have been removed from the bucket If no tokens have been removed, it 117 returns immediately.