README
¶
A leaky bucket implementation in Go.
There are at least two different definitions of the leaky bucket algorithm. This package implements the leaky bucket as a meter. For more details see:
https://en.wikipedia.org/wiki/Leaky_bucket#As_a_meter
This means it is the exact mirror of a token bucket.
// New LeakyBucket that leaks at the rate of 0.5/sec and a total capacity of 10.
b := NewLeakyBucket(0.5, 10)
b.Add(5)
b.Add(5)
// Bucket is now full!
n := b.Add(1)
// n == 0
A Collector is a convenient way to keep track of multiple LeakyBucket's. Buckets are associated with string keys for fast lookup. It can dynamically add new buckets and automatically remove them as they become empty, freeing up resources.
// New Collector that leaks at 1 MiB/sec, a total capacity of 10 MiB and
// automatic removal of bucket's when they become empty.
const megabyte = 1<<20
c := NewCollector(megabyte, megabyte*10, true)
// Attempt to add 100 MiB to a bucket associated with an IP.
n := c.Add("192.168.0.42", megabyte*100)
// 100 MiB is over the capacity, so only 10 MiB is actually added.
// n equals 10 MiB.
Documentation
¶
Overview ¶
Package leakybucket implements a scalable leaky bucket algorithm.
There are at least two different definitions of the leaky bucket algorithm. This package implements the leaky bucket as a meter. For more details see:
https://en.wikipedia.org/wiki/Leaky_bucket#As_a_meter
This means it is the exact mirror of a token bucket.
// New LeakyBucket that leaks at the rate of 0.5/sec and a total capacity of 10. b := NewLeakyBucket(0.5, 10) b.Add(5) b.Add(5) // Bucket is now full! n := b.Add(1) // n == 0
A Collector is a convenient way to keep track of multiple LeakyBucket's. Buckets are associated with string keys for fast lookup. It can dynamically add new buckets and automatically remove them as they become empty, freeing up resources.
// New Collector that leaks at 1 MiB/sec, a total capacity of 10 MiB and
// automatic removal of bucket's when they become empty.
const megabyte = 1<<20
c := NewCollector(megabyte, megabyte*10, true)
// Attempt to add 100 MiB to a bucket associated with an IP.
n := c.Add("192.168.0.42", megabyte*100)
// 100 MiB is over the capacity, so only 10 MiB is actually added.
// n equals 10 MiB.
Index ¶
- type Collector
- func (c *Collector) Add(key string, amount int64) int64
- func (c *Collector) Capacity() int64
- func (c *Collector) Count(key string) int64
- func (c *Collector) Free()
- func (c *Collector) PeriodicPrune(interval time.Duration)
- func (c *Collector) Prune()
- func (c *Collector) Rate() float64
- func (c *Collector) Remaining(key string) int64
- func (c *Collector) Remove(key string)
- func (c *Collector) Reset()
- func (c *Collector) TillEmpty(key string) time.Duration
- type LeakyBucket
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
A Collector can keep track of multiple LeakyBucket's. The caller does not directly interact with the buckets, but instead addresses them by a string key (e.g. IP address, hostname, hash, etc.) that is passed to most Collector methods.
All Collector methods are goroutine safe.
func NewCollector ¶
NewCollector creates a new Collector. When new buckets are created within the Collector, they will be assigned the capacity and rate of the Collector. A Collector does not provide a way to change the rate or capacity of bucket's within it. If different rates or capacities are required, either use multiple Collector's or manage your own LeakyBucket's.
If deleteEmptyBuckets is true, a concurrent goroutine will be run that watches for bucket's that become empty and automatically removes them, freeing up memory resources.
func (*Collector) Add ¶
Add 'amount' to the internal bucket associated with key, up to it's capacity. Returns how much was added to the bucket. If the return is less than 'amount', then the bucket's capacity was reached.
If key is not associated with a bucket internally, a new bucket is created and amount is added to it.
func (*Collector) Count ¶
Count returns the count of the internal bucket associated with key. If key is not associated with a bucket internally, it is treated as being empty.
func (*Collector) Free ¶
func (c *Collector) Free()
Free releases the collector's resources. If the collector was created with deleteEmptyBuckets = true, then the goroutine looking for empty buckets, will be stopped.
func (*Collector) PeriodicPrune ¶
PeriodicPrune runs a concurrent goroutine that calls Prune() at the given time interval.
func (*Collector) Prune ¶
func (c *Collector) Prune()
Prune removes all empty buckets in the collector.
func (*Collector) Remaining ¶
Remaining returns the remaining capacity of the internal bucket associated with key. If key is not associated with a bucket internally, it is treated as being empty.
func (*Collector) Remove ¶
Remove deletes the internal bucket associated with key. If key is not associated with a bucket internally, nothing is done.
type LeakyBucket ¶
type LeakyBucket struct {
// contains filtered or unexported fields
}
LeakyBucket represents a bucket that leaks at a constant rate.
func NewLeakyBucket ¶
func NewLeakyBucket(rate float64, capacity int64) *LeakyBucket
NewLeakyBucket creates a new LeakyBucket with the give rate and capacity.
func (*LeakyBucket) Add ¶
func (b *LeakyBucket) Add(amount int64) int64
Add 'amount' to the bucket's count, up to it's capacity. Returns how much was added to the bucket. If the return is less than 'amount', then the bucket's capacity was reached.
func (*LeakyBucket) Capacity ¶
func (b *LeakyBucket) Capacity() int64
Capacity returns the bucket's capacity.
func (*LeakyBucket) ChangeCapacity ¶
func (b *LeakyBucket) ChangeCapacity(capacity int64)
ChangeCapacity changes the bucket's capacity.
If the bucket's current count is greater than the new capacity, the count will be decreased to match the new capacity.
func (*LeakyBucket) Count ¶
func (b *LeakyBucket) Count() int64
Count returns the bucket's current count.
func (*LeakyBucket) Rate ¶
func (b *LeakyBucket) Rate() float64
Rate returns the amount the bucket leaks per second.
func (*LeakyBucket) Remaining ¶
func (b *LeakyBucket) Remaining() int64
Remaining returns the bucket's remaining capacity.
func (*LeakyBucket) TillEmpty ¶
func (b *LeakyBucket) TillEmpty() time.Duration
TillEmpty returns how much time must pass until the bucket is empty.
Source Files