BloombergLP::balb::LeakyBucket

This mechanism implements a leaky bucket that allows clients to monitor whether a resource is being consumed at a particular rate.

Synopsis

Declared in <balb_leakybucket.h>

class LeakyBucket;

Description

The behavior of a leak bucket is determined by two properties: the drain rate (in units/s) and capacity (in units), both of which can be specified at construction or using the setRateAndCapacity method.

Units can be added to a leaky bucket by either submitting them using the submit method or reserving them using the reserve method. Submitted units are removed from a leaky bucket at the drain rate, while reserved units stays unaffected in a leaky bucket until they are either cancelled (removed from the leaky bucket) using the cancelReserved method or submitted using the submitReserved method.

Adding units to a leaky bucket will cause it to overflow if after the units are added, the total number of units in the leaky bucket (including both submitted and reserved units) exceeds its capacity. A leaky bucket can be queried whether adding a specified number of units would cause it to overflow via the wouldOverflow method. If submitting units to a leaky bucket will cause it to overflow, the estimated amount of time to wait before 1 more units can be submitted without causing the leaky bucket to overflow can be determined using the calculateTimeToSubmit method.

The state of a leaky bucket must be updated manually using the updateState method supplying the current time interval. The time intervals supplied should all refer to the same time origin.

A leaky bucket keeps some statistics, including the number of submitted units, that can be accessed using the getStatistics method and reset using the resetStatistics method.

The class invariants are: * capacity() > 0 * drainRate() > 0

This class: * is exception neutral (agnostic) * is const thread‐safe For terminology see bsldoc_glossary.