github.com/larrabee/ratelimit@v1.0.6-0.20191102113931-712217ec4fdc/README.md (about)

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