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

Synopsis

Declared in <balb_ratelimiter.h>

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

Name

Description

RateLimiter [constructor]

Create a rate limiter with the specified rate limits and start time.

~RateLimiter [destructor]

Destroy this object.

calculateTimeToSubmit

Return the estimated wait before one more unit can be submitted.

cancelReserved

Cancel the specified numUnits that were previously reserved.

getStatistics

Load submitted and unused unit statistics for this rate limiter.

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.

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 statistics collected for this rate limiter.

setRateLimits

Set the sustained and peak rate limits for this rate limiter.

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.

submitReserved

Submit the specified numUnits that were previously reserved.

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.

wouldExceedBandwidth

Return whether submitting 1 unit at currentTime would exceed limits.

Static Member Functions

Name

Description

supportsRateLimitsExactly

Return whether the given limits are preserved exactly by this class.

Created with MrDocs