[#BloombergLP-balb-LeakyBucket]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balb.adoc[balb]::LeakyBucket
:relfileprefix: ../../
:mrdocs:

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>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
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`.

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balb/LeakyBucket/2constructor.adoc[`LeakyBucket`]         [.small]#[constructor]#
| Create an empty leaky bucket with the specified rate and capacity.
| xref:BloombergLP/balb/LeakyBucket/2destructor.adoc[`~LeakyBucket`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/balb/LeakyBucket/calculateTimeToSubmit.adoc[`calculateTimeToSubmit`] 
| Return the estimated wait before one more unit can be submitted.
| xref:BloombergLP/balb/LeakyBucket/cancelReserved.adoc[`cancelReserved`] 
| Cancel the specified `numUnits` that were previously reserved.
| xref:BloombergLP/balb/LeakyBucket/capacity.adoc[`capacity`] 
| Return the capacity of this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/drainRate.adoc[`drainRate`] 
| Return the drain rate of this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/getStatistics.adoc[`getStatistics`] 
| Load submitted and unused unit statistics for this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/lastUpdateTime.adoc[`lastUpdateTime`] 
| Return the time interval when this leaky bucket was last updated.
| xref:BloombergLP/balb/LeakyBucket/reserve.adoc[`reserve`] 
| Reserve the specified `numUnits` for future use by this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/reset.adoc[`reset`] 
| Reset the counters and update times for this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/resetStatistics.adoc[`resetStatistics`] 
| Reset the statistics collected for this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/setRateAndCapacity.adoc[`setRateAndCapacity`] 
| Set the drain rate and capacity of this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/statisticsCollectionStartTime.adoc[`statisticsCollectionStartTime`] 
| Return the time interval when the collection of the statistics (as returned by `getStatistics`) started.
| xref:BloombergLP/balb/LeakyBucket/submit.adoc[`submit`] 
| Submit the specified `numUnits` to this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/submitReserved.adoc[`submitReserved`] 
| Submit the specified `numUnits` that were previously reserved.
| xref:BloombergLP/balb/LeakyBucket/unitsInBucket.adoc[`unitsInBucket`] 
| Return the number of submitted units in this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/unitsReserved.adoc[`unitsReserved`] 
| Return the number of reserved units in this leaky bucket.
| xref:BloombergLP/balb/LeakyBucket/updateState.adoc[`updateState`] 
| Update this leaky bucket's state to the specified `currentTime`.
| xref:BloombergLP/balb/LeakyBucket/wouldOverflow.adoc[`wouldOverflow`] 
| Return whether submitting one more unit would exceed capacity.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balb/LeakyBucket/calculateCapacity.adoc[`calculateCapacity`] 
| Return the capacity for a leaky bucket with the given rate and window.
| xref:BloombergLP/balb/LeakyBucket/calculateDrainTime.adoc[`calculateDrainTime`] 
| Return the time interval required to drain the specified units.
| xref:BloombergLP/balb/LeakyBucket/calculateTimeWindow.adoc[`calculateTimeWindow`] 
| Return the time window approximated by a leaky bucket of given size.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#