BDE 4.14.0 Production release
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
balb::LeakyBucket Class Reference

#include <balb_leakybucket.h>

Public Member Functions

 LeakyBucket (bsls::Types::Uint64 drainRate, bsls::Types::Uint64 capacity, const bsls::TimeInterval &currentTime)
 
 ~LeakyBucket ()
 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 setRateAndCapacity (bsls::Types::Uint64 newRate, bsls::Types::Uint64 newCapacity)
 
void submit (bsls::Types::Uint64 numUnits)
 
void submitReserved (bsls::Types::Uint64 numUnits)
 
void updateState (const bsls::TimeInterval &currentTime)
 
bool wouldOverflow (const bsls::TimeInterval &currentTime)
 
bsls::Types::Uint64 capacity () const
 Return the capacity of this leaky bucket.
 
bsls::Types::Uint64 drainRate () const
 Return the drain rate of this leaky bucket.
 
void getStatistics (bsls::Types::Uint64 *submittedUnits, bsls::Types::Uint64 *unusedUnits) const
 
bsls::TimeInterval lastUpdateTime () const
 Return the time interval when this leaky bucket was last updated.
 
bsls::TimeInterval statisticsCollectionStartTime () const
 
bsls::Types::Uint64 unitsInBucket () const
 Return the number of submitted units in this leaky bucket.
 
bsls::Types::Uint64 unitsReserved () const
 Return the number of reserved units in this leaky bucket.
 

Static Public Member Functions

static bsls::Types::Uint64 calculateCapacity (bsls::Types::Uint64 drainRate, const bsls::TimeInterval &timeWindow)
 
static bsls::TimeInterval calculateDrainTime (bsls::Types::Uint64 numUnits, bsls::Types::Uint64 drainRate, bool ceilFlag)
 
static bsls::TimeInterval calculateTimeWindow (bsls::Types::Uint64 drainRate, bsls::Types::Uint64 capacity)
 

Detailed Description

This mechanism implements a leaky bucket that allows clients to monitor whether a resource is being consumed at a particular rate. The behavior of a leak bucket is determined by two properties: the drain rate (in units/s) and capacity (in units), both of which can be specified at construction or using the setRateAndCapacity method.

Units can be added to a leaky bucket by either submitting them using the submit method or reserving them using the reserve method. Submitted units are removed from a leaky bucket at the drain rate, while reserved units stays unaffected in a leaky bucket until they are either cancelled (removed from the leaky bucket) using the cancelReserved method or submitted using the submitReserved method.

Adding units to a leaky bucket will cause it to overflow if after the units are added, the total number of units in the leaky bucket (including both submitted and reserved units) exceeds its capacity. A leaky bucket can be queried whether adding a specified number of units would cause it to overflow via the wouldOverflow method. If submitting units to a leaky bucket will cause it to overflow, the estimated amount of time to wait before 1 more units can be submitted without causing the leaky bucket to overflow can be determined using the calculateTimeToSubmit method.

The state of a leaky bucket 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 leaky bucket keeps some statistics, including the number of submitted units, that can be accessed using the getStatistics method and reset using the resetStatistics method.

The class invariants are:

This class:

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

See balb_leakybucket

Constructor & Destructor Documentation

◆ LeakyBucket()

balb::LeakyBucket::LeakyBucket ( bsls::Types::Uint64  drainRate,
bsls::Types::Uint64  capacity,
const bsls::TimeInterval &  currentTime 
)

Create an empty leaky bucket having the specified drainRate, the specified capacity, and the specified currentTime as the initial lastUpdateTime. The behavior is undefined unless 0 < newRate, 0 < newCapacity, and LLONG_MIN != currentTime.seconds().

◆ ~LeakyBucket()

balb::LeakyBucket::~LeakyBucket ( )
inline

Member Function Documentation

◆ calculateCapacity()

static bsls::Types::Uint64 balb::LeakyBucket::calculateCapacity ( bsls::Types::Uint64  drainRate,
const bsls::TimeInterval &  timeWindow 
)
static

Return the capacity of a leaky bucket as the rounded-down product of the specified drainRate by the specified timeWindow. If the result evaluates to 0, return 1. The behavior is undefined unless the product of drainRate and timeWindow can be represented by a 64-bit unsigned integral type.

◆ calculateDrainTime()

static bsls::TimeInterval balb::LeakyBucket::calculateDrainTime ( bsls::Types::Uint64  numUnits,
bsls::Types::Uint64  drainRate,
bool  ceilFlag 
)
static

Return the time interval required to drain the specified numUnits at the specified drainRate, round up the number of nanoseconds in the time interval if the specified ceilFlag is set to true, otherwise, round down the number of nanoseconds. The behavior is undefined unless the number of seconds in the calculated interval may be represented by a 64-bit signed integral type.

◆ calculateTimeToSubmit()

bsls::TimeInterval balb::LeakyBucket::calculateTimeToSubmit ( const bsls::TimeInterval &  currentTime)

If 1 more unit can be submitted to this leaky bucket without causing it to overflow, then return a time interval of 0 immediately. Otherwise, first update the state of this leaky bucket to the specified currentTime. Then, return the estimated time interval that should pass from currentTime until 1 more unit can be submitted to this leaky bucket without causing it to overflow. The number of nanoseconds in the returned time interval is rounded up. Note that a time interval of 0 can still be return after the state of this leaky bucket has been updated to 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. The behavior is undefined unless LLONG_MIN != currentTime.seconds() and the total number of seconds in the time interval resulting from currentTime - lastUpdateTime() can be represented with a 64-bit signed integer.

◆ calculateTimeWindow()

static bsls::TimeInterval balb::LeakyBucket::calculateTimeWindow ( bsls::Types::Uint64  drainRate,
bsls::Types::Uint64  capacity 
)
static

Return the time interval over which a leaky bucket approximates a moving-total of submitted units, as the rounded-down ratio between the specified capacity and the specified drainRate. If the rounded ratio is 0, return a time interval of 1 nanosecond. The behavior is undefined unless drainRate > 0 and capacity / drainRate can be represented with 64-bit signed integral type.

◆ cancelReserved()

void balb::LeakyBucket::cancelReserved ( bsls::Types::Uint64  numUnits)
inline

Cancel the specified numUnits that were previously reserved. This method reduces the number of reserved units by numUnits. The behavior is undefined unless numUnits <= unitsReserved().

◆ capacity()

bsls::Types::Uint64 balb::LeakyBucket::capacity ( ) const
inline

◆ drainRate()

bsls::Types::Uint64 balb::LeakyBucket::drainRate ( ) const
inline

◆ getStatistics()

void balb::LeakyBucket::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 leaky bucket from the statisticsCollectionStartTime to the lastUpdateTime. The number of unused units is the difference between the number of units that could have been consumed and the number of units actually submitted for the time period.

◆ lastUpdateTime()

bsls::TimeInterval balb::LeakyBucket::lastUpdateTime ( ) const
inline

◆ reserve()

void balb::LeakyBucket::reserve ( bsls::Types::Uint64  numUnits)
inline

Reserve the specified numUnits for future use by this leaky bucket. The behavior is undefined unless 'unitsReserved() + unitsInBucket() + numOfUnits' can be represented by a 64-bit unsigned integral type. Note that after this operation, this bucket may overflow. Also note that the time interval between the invocations of reserve and submitReserved or cancelReserved should be kept as short as possible; otherwise, the precision of the time interval calculated by calculateTimeToSubmit may be negatively affected.

◆ reset()

void balb::LeakyBucket::reset ( const bsls::TimeInterval &  currentTime)
inline

Reset the following statistic counters for this leaky bucket to 0: unitsInBucket, unitsReserved, submittedUnits, and unusedUnits. Set the lastUpdateTime and the statisticCollectionStartTime to the specified currentTime of this leaky bucket. The behavior is undefined unless 'LLONG_MIN != currentTime.seconds()'.

◆ resetStatistics()

void balb::LeakyBucket::resetStatistics ( )
inline

Reset the statics collected for this leaky bucket 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.

◆ setRateAndCapacity()

void balb::LeakyBucket::setRateAndCapacity ( bsls::Types::Uint64  newRate,
bsls::Types::Uint64  newCapacity 
)

Set the drain rate of this leaky bucket to the specified newRate and the capacity of this leaky bucket to the specified newCapacity. The behavior is undefined unless 0 < newRate and 0 < newCapacity.

◆ statisticsCollectionStartTime()

bsls::TimeInterval balb::LeakyBucket::statisticsCollectionStartTime ( ) const
inline

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

◆ submit()

void balb::LeakyBucket::submit ( bsls::Types::Uint64  numUnits)
inline

Submit the specified numUnits to this leaky bucket. The behavior is undefined unless unitsReserved() + unitsInBucket() + numUnits can be represented by a 64-bit unsigned integral type. Note that after this operation, this leaky bucket may overflow.

◆ submitReserved()

void balb::LeakyBucket::submitReserved ( bsls::Types::Uint64  numUnits)
inline

Submit the specified numUnits that were previously reserved. This method reduces the number of reserved units by numUnits and submits numUnits to this leaky bucket. The behavior is undefined unless numUnits <= unitsReserved().

◆ unitsInBucket()

bsls::Types::Uint64 balb::LeakyBucket::unitsInBucket ( ) const
inline

◆ unitsReserved()

bsls::Types::Uint64 balb::LeakyBucket::unitsReserved ( ) const
inline

◆ updateState()

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

Set the lastUpdateTime of this leaky bucket to the specified currentTime. If currentTime is after lastUpdateTime, then update the unitsInBucket of this leaky bucket by subtracting from it the number of units drained from lastUpdateTime to currentTime. If currentTime is before the statisticsCollectionStartTime of this leaky bucket, set statisticsCollectionStartTime to currentTime. The behavior is undefined unless LLONG_MIN != currentTime.seconds() and the total number of seconds in the time interval resulting from currentTime - lastUpdateTime() can be represented with a 64-bit signed integer.

◆ wouldOverflow()

bool balb::LeakyBucket::wouldOverflow ( const bsls::TimeInterval &  currentTime)

Update the state of this this leaky bucket to the specified currentTime, and return true if adding 1 more unit to this leaky bucket would cause the total number of units held by this leaky bucket to exceed its capacity, and false otherwise. Note that this method counts both submitted units and reserved units toward the total number of units held by this leaky bucket. The behavior is undefined unless LLONG_MIN != currentTime.seconds() and the total number of seconds in the time interval resulting from currentTime - lastUpdateTime() can be represented with a 64-bit signed integer.

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