[#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&period;

== Synopsis

Declared in `&lt;balb&lowbar;ratelimiter&period;h&gt;`

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

== Description

The behavior of a rate limiter is determined by four properties&colon; the sustained rate (in units&sol;s), the sustained&hyphen;rate time&hyphen;window (in seconds), the peak rate (in units&sol;s), and the peak&hyphen;rate time&hyphen;window (in seconds)&period; All of these properties can be specified at construction or using the `setRateLimits` method&period;

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

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

The state of a rate limiter must be updated manually using the `updateState` method supplying the current time interval&period; The time intervals supplied should all refer to the same time origin&period;

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&period;

This class&colon; &ast; is _exception_ _neutral_ (agnostic) &ast; is _const_ _thread&hyphen;safe_ For terminology see `bsldoc&lowbar;glossary`&period;

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


== 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&period;
|===



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