leakybucket

package
v4.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 26, 2024 License: GPL-3.0, MIT Imports: 5 Imported by: 7

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

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

func NewCollector(rate float64, capacity int64, period time.Duration, deleteEmptyBuckets bool) *Collector

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

func (c *Collector) Add(key string, amount int64) int64

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) Capacity

func (c *Collector) Capacity() int64

Capacity returns the collector's capacity.

func (*Collector) Count

func (c *Collector) Count(key string) int64

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

func (c *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) Rate

func (c *Collector) Rate() float64

Rate returns the collector's rate.

func (*Collector) Remaining

func (c *Collector) Remaining(key string) int64

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

func (c *Collector) Remove(key string)

Remove deletes the internal bucket associated with key. If key is not associated with a bucket internally, nothing is done.

func (*Collector) Reset

func (c *Collector) Reset()

Reset removes all internal buckets and resets the collector back to as if it was just created.

func (*Collector) TillEmpty

func (c *Collector) TillEmpty(key string) time.Duration

TillEmpty returns how much time must pass until the internal bucket associated with key is empty. If key is not associated with a bucket internally, it is treated as being empty.

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, period time.Duration) *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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL