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

This mechanism implements a rate limiter that allows clients to monitor and control resource consumption rates.

== Synopsis

Declared in `<balb_ratelimiter.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class RateLimiter;
----

== Description

The behavior of a rate limiter is determined by four properties: the sustained rate (in units/s), the sustained‐rate time‐window (in seconds), the peak rate (in units/s), and the peak‐rate time‐window (in seconds). All of these properties can be specified at construction or using the `setRateLimits` method.

Units can be indicated to a rate limiter as consumed by either submitting them using the `submit` method. Units can be marked as reserved, which effectively shorten the sustained‐rate time‐window and the peak‐rate time‐window, by using the `reserve` method.

Whether submitting 1 more unit would exceed the configured limits can be determined using the `wouldExceedBandwidth` method. The estimated amount of time to wait before 1 more unit will be allowed to be submitted can be determined using the `calculateTimeToSubmit` method.

The state of a rate limiter 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 rate limiter keeps some statistics, including the number of submitted units, that can be accessed using the `getStatistics` and reset using the `resetStatistics` method.

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/RateLimiter/2constructor.adoc[`RateLimiter`]         [.small]#[constructor]#
| Create a rate limiter with the specified rate limits and start time.
| xref:BloombergLP/balb/RateLimiter/2destructor.adoc[`~RateLimiter`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/balb/RateLimiter/calculateTimeToSubmit.adoc[`calculateTimeToSubmit`] 
| Return the estimated wait before one more unit can be submitted.
| xref:BloombergLP/balb/RateLimiter/cancelReserved.adoc[`cancelReserved`] 
| Cancel the specified `numUnits` that were previously reserved.
| xref:BloombergLP/balb/RateLimiter/getStatistics.adoc[`getStatistics`] 
| Load submitted and unused unit statistics for this rate limiter.
| xref:BloombergLP/balb/RateLimiter/lastUpdateTime.adoc[`lastUpdateTime`] 
| Return the time when this rate limiter was last updated.
| xref:BloombergLP/balb/RateLimiter/peakRateLimit.adoc[`peakRateLimit`] 
| Return the peak rate of this rate limiter.
| xref:BloombergLP/balb/RateLimiter/peakRateWindow.adoc[`peakRateWindow`] 
| Return the peak‐rate time‐period of this rate limiter. Note that this period is generally significantly shorter than `sustainedRateWindow`.
| xref:BloombergLP/balb/RateLimiter/reserve.adoc[`reserve`] 
| Reserve the specified `numUnits` for future use by this rate limiter.
| xref:BloombergLP/balb/RateLimiter/reset.adoc[`reset`] 
| Reset the statistics counter for this rate limiter to 0, and set the `lastUpdateTime` of this rate limiter to the specified `currentTime`.
| xref:BloombergLP/balb/RateLimiter/resetStatistics.adoc[`resetStatistics`] 
| Reset the statistics collected for this rate limiter.
| xref:BloombergLP/balb/RateLimiter/setRateLimits.adoc[`setRateLimits`] 
| Set the sustained and peak rate limits for this rate limiter.
| xref:BloombergLP/balb/RateLimiter/statisticsCollectionStartTime.adoc[`statisticsCollectionStartTime`] 
| Return the time interval when the collection of the statistics (as returned by `getStatistics`) started.
| xref:BloombergLP/balb/RateLimiter/submit.adoc[`submit`] 
| Submit the specified `numUnits` to this rate limiter.
| xref:BloombergLP/balb/RateLimiter/submitReserved.adoc[`submitReserved`] 
| Submit the specified `numUnits` that were previously reserved.
| xref:BloombergLP/balb/RateLimiter/sustainedRateLimit.adoc[`sustainedRateLimit`] 
| Return the sustained rate of this rate limiter.
| xref:BloombergLP/balb/RateLimiter/sustainedRateWindow.adoc[`sustainedRateWindow`] 
| Return the sustained‐rate time‐period of this rate limiter. Note that this period is generally significantly longer than the `peakRateWindow`.
| xref:BloombergLP/balb/RateLimiter/unitsReserved.adoc[`unitsReserved`] 
| Return the number of reserved units for this rate limiter.
| xref:BloombergLP/balb/RateLimiter/updateState.adoc[`updateState`] 
| Set the `lastUpdateTime` of this rate limiter to the specified `currentTime`.
| xref:BloombergLP/balb/RateLimiter/wouldExceedBandwidth.adoc[`wouldExceedBandwidth`] 
| Return whether submitting 1 unit at `currentTime` would exceed limits.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balb/RateLimiter/supportsRateLimitsExactly.adoc[`supportsRateLimitsExactly`] 
| Return whether the given limits are preserved exactly by this class.
|===



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