This mechanism implements a rate limiter that allows clients to monitor and control the usage of a resource such that the rate of consumption stays within configured limits. 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.

Synopsis

Declared in <balb_ratelimiter.h>

class RateLimiter;

Description

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

Name

Description

RateLimiter [constructor]

Create a RateLimiter object, having the specified sustainedRateLimit, the specified sustainedRateWindow, the specified peakRateLimit, the specified peakRateWindow, and using the specified currentTime as the initial lastUpdateTime. The behavior is undefined unless 0 < sustainedRateLimit, 0 < sustainedRateWindow, 0 < peakRateLimit, 0 < peakRateWindow, the product of sustainedRateLimit and sustainedRateWindow can be represented by 64‐bit unsigned integral type, and the product of peakRateLimit and peakRateWindow can be represented by 64‐bit unsigned integral type.

~RateLimiter [destructor]

Destroy this object.

calculateTimeToSubmit

Update the state of this rate limiter to the specified currentTime. Return the estimated time interval that should pass from currentTime until 1 more unit can be submitted to this rate limiter without exceeding its configured limits. The number of nanoseconds in the returned time interval is rounded up. Note that a time interval of 0 is returned if 1 or more units can be submitted at currentTime. Also note that after waiting for the returned time interval, clients should typically check again using this method, because additional units may have been submitted in the interim.

cancelReserved

Cancel the specified numUnits that were previously reserved. The behavior is undefined unless numUnits <= unitsReserved().

getStatistics

Load, into the specified submittedUnits and the specified unusedUnits respectively, the numbers of submitted units and the number of unused units for this rate limiter from the statisticsCollectionStartTime to the 'lastUpdateTime. The number of unused units is the difference between the number of units that could have been consumed at the sustained rate and the number of units actually submitted for the time period.

lastUpdateTime

Return the time when this rate limiter was last updated.

peakRateLimit

Return the peak rate of this rate limiter.

peakRateWindow

Return the peak‐rate time‐period of this rate limiter. Note that this period is generally significantly shorter than sustainedRateWindow.

reserve

Reserve the specified numUnits for future use by this rate limiter. The behavior is undefined unless the sum of numUnits, unused units previously submitted to this rate limiter, and unitsReserved can be represented by a 64‐bit unsigned integral type.

reset

Reset the statistics counter for this rate limiter to 0, and set the lastUpdateTime of this rate limiter to the specified currentTime.

resetStatistics

Reset the statics collected for this rate limiter by setting the number of units used and the number of units submitted to 0, and set the statisticsCollectionStartTime to the lastUpdateTime of this leaky bucket.

setRateLimits

Set the sustained rate of this rate limiter to the specified sustainedRateLimit, the sustained‐rate time‐window to the specified sustainedRateWindow, the peak rate to the specified peakRateLimit and the peak‐rate time‐window to the specified peakRateWindow. The behavior is undefined unless 0 < sustainedRateLimit, 0 < sustainedRateWindow, 0 < peakRateLimit, 0 < peakRateWindow, the product of sustainedRateLimit and sustainedRateWindow can be represented by 64‐bit unsigned integral type, and the product of peakRateLimit and peakRateWindow can be represented by 64‐bit unsigned integral type.

statisticsCollectionStartTime

Return the time interval when the collection of the statistics (as returned by getStatistics) started.

submit

Submit the specified numUnits to this rate limiter. The behavior is undefined unless the sum of numUnits, unused units previously submitted to this rate limiter, and unitsReserved can be represented by a 64‐bit unsigned integral type.

submitReserved

Submit the specified numUnits that were previously reserved. The behavior is undefined unless numUnits <= unitsReserved().

sustainedRateLimit

Return the sustained rate of this rate limiter.

sustainedRateWindow

Return the sustained‐rate time‐period of this rate limiter. Note that this period is generally significantly longer than the peakRateWindow.

unitsReserved

Return the number of reserved units for this rate limiter.

updateState

Set the lastUpdateTime of this rate limiter to the specified currentTime. If the currentTime is after lastUpdateTime, then recalculate number of units available for consumption based on the peakRate, sustainedRate and the time interval between lastUpdateTime and currentTime. If currentTime is before statisticsCollectionStartTime, set it' to currentTime.

wouldExceedBandwidth

Update the state of this rate limiter to the specified currentTime. Return true if submitting 1 unit at the currentTime would exceed the configured limits, and false otherwise.

Static Member Functions

Name

Description

supportsRateLimitsExactly

Returns true if, supposing the specified sustainedRateLimit, sustainedRateWindow, peakRateLimit, and peakRateWindow are used to initialize a RateLimiter object, the corresponding query methods return the same values. The implementation of RateLimiter uses balb::LeakyBucket objects, and for some combinations of values the capacity of the balb::LeakyBucket is rounded such that the rederived values differ. Note that this method is most likely to return true when the product of each corresponding pair of limit and window (as a fraction of a second) is integral.

Created with MrDocs