balb::RateLimiter Class Reference

#include <balb_ratelimiter.h>

Public Member Functions
	RateLimiter (bsls::Types::Uint64 sustainedRateLimit, const bsls::TimeInterval &sustainedRateWindow, bsls::Types::Uint64 peakRateLimit, const bsls::TimeInterval &peakRateWindow, const bsls::TimeInterval &currentTime)
	~RateLimiter ()
	Destroy this object.
bsls::TimeInterval	calculateTimeToSubmit (const bsls::TimeInterval &currentTime)
void	cancelReserved (bsls::Types::Uint64 numUnits)
void	reserve (bsls::Types::Uint64 numUnits)
void	reset (const bsls::TimeInterval &currentTime)
void	resetStatistics ()
void	setRateLimits (bsls::Types::Uint64 sustainedRateLimit, const bsls::TimeInterval &sustainedRateWindow, bsls::Types::Uint64 peakRateLimit, const bsls::TimeInterval &peakRateWindow)
void	submit (bsls::Types::Uint64 numUnits)
void	submitReserved (bsls::Types::Uint64 numUnits)
void	updateState (const bsls::TimeInterval &currentTime)
bool	wouldExceedBandwidth (const bsls::TimeInterval &currentTime)
void	getStatistics (bsls::Types::Uint64 *submittedUnits, bsls::Types::Uint64 *unusedUnits) const
bsls::TimeInterval	lastUpdateTime () const
	Return the time when this rate limiter was last updated.
bsls::Types::Uint64	peakRateLimit () const
	Return the peak rate of this rate limiter.
bsls::TimeInterval	peakRateWindow () const
bsls::TimeInterval	statisticsCollectionStartTime () const
bsls::Types::Uint64	sustainedRateLimit () const
	Return the sustained rate of this rate limiter.
bsls::TimeInterval	sustainedRateWindow () const
bsls::Types::Uint64	unitsReserved () const
	Return the number of reserved units for this rate limiter.

Static Public Member Functions
static bool	supportsRateLimitsExactly (bsls::Types::Uint64 sustainedRateLimit, const bsls::TimeInterval &sustainedRateWindow, bsls::Types::Uint64 peakRateLimit, const bsls::TimeInterval &peakRateWindow)

Detailed Description

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:

• is exception neutral (agnostic)
• is const thread-safe For terminology see bsldoc_glossary .

See balb_ratelimiter

Constructor & Destructor Documentation

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.

~RateLimiter()

balb::RateLimiter::~RateLimiter

(

)

Member Function Documentation

calculateTimeToSubmit()

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.

cancelReserved()

void balb::RateLimiter::cancelReserved ( bsls::Types::Uint64  numUnits )

inline

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

getStatistics()

void balb::RateLimiter::getStatistics ( bsls::Types::Uint64 *  submittedUnits, bsls::Types::Uint64 *  unusedUnits  ) const

inline

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()

bsls::TimeInterval balb::RateLimiter::lastUpdateTime ( ) const

inline

peakRateLimit()

bsls::Types::Uint64 balb::RateLimiter::peakRateLimit ( ) const

inline

peakRateWindow()

bsls::TimeInterval balb::RateLimiter::peakRateWindow ( ) const

inline

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

reserve()

void balb::RateLimiter::reserve ( bsls::Types::Uint64  numUnits )

inline

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()

void balb::RateLimiter::reset ( const bsls::TimeInterval &  currentTime )

inline

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

resetStatistics()

void balb::RateLimiter::resetStatistics ( )

inline

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()

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.

statisticsCollectionStartTime()

bsls::TimeInterval balb::RateLimiter::statisticsCollectionStartTime ( ) const

inline

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

submit()

void balb::RateLimiter::submit ( bsls::Types::Uint64  numUnits )

inline

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()

void balb::RateLimiter::submitReserved ( bsls::Types::Uint64  numUnits )

inline

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

supportsRateLimitsExactly()

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.

sustainedRateLimit()

bsls::Types::Uint64 balb::RateLimiter::sustainedRateLimit ( ) const

inline

sustainedRateWindow()

bsls::TimeInterval balb::RateLimiter::sustainedRateWindow ( ) const

inline

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

unitsReserved()

bsls::Types::Uint64 balb::RateLimiter::unitsReserved ( ) const

inline

updateState()

void balb::RateLimiter::updateState ( const bsls::TimeInterval &  currentTime )

inline

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()

bool balb::RateLimiter::wouldExceedBandwidth ( const bsls::TimeInterval &  currentTime )

inline

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.

---

The documentation for this class was generated from the following file:

• balb_ratelimiter.h