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.