|
Quick Links: |
#include <balb_ratelimiter.h>
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.
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:
For terminology see bsldoc_glossary.
See Component balb_ratelimiter
| balb::RateLimiter::RateLimiter | ( | bsls::Types::Uint64 | sustainedRateLimit, | |
| const bsls::TimeInterval & | sustainedRateWindow, | |||
| bsls::Types::Uint64 | peakRateLimit, | |||
| const bsls::TimeInterval & | peakRateWindow, | |||
| const bsls::TimeInterval & | currentTime | |||
| ) |
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.
| balb::RateLimiter::~RateLimiter | ( | ) |
Destroy this object.
| static bool balb::RateLimiter::supportsRateLimitsExactly | ( | bsls::Types::Uint64 | sustainedRateLimit, | |
| const bsls::TimeInterval & | sustainedRateWindow, | |||
| bsls::Types::Uint64 | peakRateLimit, | |||
| const bsls::TimeInterval & | peakRateWindow | |||
| ) | [static] |
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.
| bsls::TimeInterval balb::RateLimiter::calculateTimeToSubmit | ( | const bsls::TimeInterval & | currentTime | ) |
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.
| void balb::RateLimiter::cancelReserved | ( | bsls::Types::Uint64 | numUnits | ) |
Cancel the specified numUnits that were previously reserved. The behavior is undefined unless numUnits <= unitsReserved().
| void balb::RateLimiter::reserve | ( | bsls::Types::Uint64 | numUnits | ) |
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.
| void balb::RateLimiter::reset | ( | const bsls::TimeInterval & | currentTime | ) |
Reset the statistics counter for this rate limiter to 0, and set the lastUpdateTime of this rate limiter to the specified currentTime.
| void balb::RateLimiter::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.
| void balb::RateLimiter::setRateLimits | ( | bsls::Types::Uint64 | sustainedRateLimit, | |
| const bsls::TimeInterval & | sustainedRateWindow, | |||
| bsls::Types::Uint64 | peakRateLimit, | |||
| const bsls::TimeInterval & | peakRateWindow | |||
| ) |
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.
| void balb::RateLimiter::submit | ( | bsls::Types::Uint64 | numUnits | ) |
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.
| void balb::RateLimiter::submitReserved | ( | bsls::Types::Uint64 | numUnits | ) |
Submit the specified numUnits that were previously reserved. The behavior is undefined unless numUnits <= unitsReserved().
| void balb::RateLimiter::updateState | ( | const bsls::TimeInterval & | currentTime | ) |
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.
| bool balb::RateLimiter::wouldExceedBandwidth | ( | const bsls::TimeInterval & | currentTime | ) |
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.
| void balb::RateLimiter::getStatistics | ( | bsls::Types::Uint64 * | submittedUnits, | |
| bsls::Types::Uint64 * | unusedUnits | |||
| ) | const |
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.
| bsls::TimeInterval balb::RateLimiter::lastUpdateTime | ( | ) | const |
Return the time when this rate limiter was last updated.
| bsls::Types::Uint64 balb::RateLimiter::peakRateLimit | ( | ) | const |
Return the peak rate of this rate limiter.
| bsls::TimeInterval balb::RateLimiter::peakRateWindow | ( | ) | const |
Return the peak-rate time-period of this rate limiter. Note that this period is generally significantly shorter than sustainedRateWindow.
| bsls::TimeInterval balb::RateLimiter::statisticsCollectionStartTime | ( | ) | const |
Return the time interval when the collection of the statistics (as returned by getStatistics) started.
| bsls::Types::Uint64 balb::RateLimiter::sustainedRateLimit | ( | ) | const |
Return the sustained rate of this rate limiter.
| bsls::TimeInterval balb::RateLimiter::sustainedRateWindow | ( | ) | const |
Return the sustained-rate time-period of this rate limiter. Note that this period is generally significantly longer than the peakRateWindow.
| bsls::Types::Uint64 balb::RateLimiter::unitsReserved | ( | ) | const |
Return the number of reserved units for this rate limiter.
1.7.1