bdlmt::Throttle Class Reference

#include <bdlmt_throttle.h>

Public Member Functions
void	initialize (int maxSimultaneousActions, Int64 nanosecondsPerAction, bsls::SystemClockType::Enum clockType=bsls::SystemClockType::e_MONOTONIC)
void	initialize (int maxSimultaneousActions, Int64 nanosecondsPerAction, const bsl::chrono::system_clock &)
void	initialize (int maxSimultaneousActions, Int64 nanosecondsPerAction, const bsl::chrono::steady_clock &)
bool	requestPermission ()
bool	requestPermission (const bsls::TimeInterval &now)
bool	requestPermission (int numActions)
bool	requestPermission (int numActions, const bsls::TimeInterval &now)
int	requestPermissionIfValid (bool *result, int numActions)
int	requestPermissionIfValid (bool *result, int numActions, const bsls::TimeInterval &now)
bsls::SystemClockType::Enum	clockType () const
int	maxSimultaneousActions () const
Int64	nanosecondsPerAction () const
int	nextPermit (bsls::TimeInterval *result, int numActions) const

Public Attributes
AtomicTypes::Int64	d_prevLeakTime
Int64	d_nanosecondsPerAction
Int64	d_nanosecondsPerTotalReset
int	d_maxSimultaneousActions
bsls::SystemClockType::Enum	d_clockType

Static Public Attributes
static const Int64	k_TEN_YEARS_NANOSECONDS

Friends
template<int t_MAX_SIMULTANEOUS_ACTIONS, bsls::Types::Int64 t_NANOSECONDS_PER_ACTION>
class	Throttle_InitHelper

Detailed Description

This class provides a mechanism that can be used by clients to regulate the frequency at which actions can be taken. The data members of Throttle are currently public to allow for compile-time (aggregate) initialization of Throttle objects having static storage duration (for C++03 compilers that do not provide constexpr).

See bdlmt_throttle

Member Function Documentation

clockType()

bsls::SystemClockType::Enum bdlmt::Throttle::clockType ( ) const

inline

Return the system clock type with which this Throttle is configured to observe the passage of time.

initialize() [1/3]

void bdlmt::Throttle::initialize	(	int	maxSimultaneousActions,
		Int64	nanosecondsPerAction,
		bsls::SystemClockType::Enum	clockType = bsls::SystemClockType::e_MONOTONIC
	)

Initialize this Throttle to limit the average period of actions permitted to the specified nanosecondsPerAction, and the maximum number of simultaneous actions allowed to the specified maxSimultaneousActions. Optionally specify clockType to indicate the system clock that will be used to measure time (see Supported Clock-Types . If clockType is not supplied the monotonic system clock is used. The configured throttle will over time limit the average number of actions permitted to a rate of 1 / nanosecondsPerAction. If maxSimultaneousActions is 0, the throttle will be configured to permit no actions, otherwise if nanosecondsPerAction is 0, the throttle will be configured to permit all actions. The behavior is undefined unless 0 <= nanosecondsPerAction, 0 <= maxSimultaneousActions, 0 < nanosecondsPerAction || 0 < maxSimultaneousActions, and maxSimultaneousActions * nanosecondsPerActionLeak <= LLONG_MAX. Note that the behavior for other methods is undefined unless this Throttle is initialized (either using one of the overloads of this function, or a BDLMT_THROTTLE_INIT macro) prior to being called.

initialize() [2/3]

void bdlmt::Throttle::initialize ( int  maxSimultaneousActions, Int64  nanosecondsPerAction, const bsl::chrono::steady_clock &    )

inline

Initialize this Throttle to limit the average period of actions permitted to the specified nanosecondsPerAction, and the maximum number of simultaneous actions allowed to the specified maxSimultaneousActions. Use the monotonic system clock to measure time (see Supported Clock-Types . The configured throttle will over time limit the average number of actions permitted to a rate of 1 / nanosecondsPerAction. If maxSimultaneousActions is 0, the throttle will be configured to permit no actions, otherwise if nanosecondsPerAction is 0, the throttle will be configured to permit all actions. The behavior is undefined unless 0 <= nanosecondsPerAction, 0 <= maxSimultaneousActions, 0 < nanosecondsPerAction || 0 < maxSimultaneousActions, and maxSimultaneousActions * nanosecondsPerActionLeak <= LLONG_MAX. Note that the behavior for other methods is undefined unless this Throttle is initialized (either using one of the overloads of this function, or a BDLMT_THROTTLE_INIT macro) prior to being called.

initialize() [3/3]

void bdlmt::Throttle::initialize ( int  maxSimultaneousActions, Int64  nanosecondsPerAction, const bsl::chrono::system_clock &    )

inline

Initialize this Throttle to limit the average period of actions permitted to the specified nanosecondsPerAction, and the maximum number of simultaneous actions allowed to the specified maxSimultaneousActions. Use the realtime system clock to measure time (see Supported Clock-Types . The configured throttle will over time limit the average number of actions permitted to a rate of 1 / nanosecondsPerAction. If maxSimultaneousActions is 0, the throttle will be configured to permit no actions, otherwise if nanosecondsPerAction is 0, the throttle will be configured to permit all actions. The behavior is undefined unless 0 <= nanosecondsPerAction, 0 <= maxSimultaneousActions, 0 < nanosecondsPerAction || 0 < maxSimultaneousActions, and maxSimultaneousActions * nanosecondsPerActionLeak <= LLONG_MAX. Note that the behavior for other methods is undefined unless this Throttle is initialized (either using one of the overloads of this function, or a BDLMT_THROTTLE_INIT macro) prior to being called.

maxSimultaneousActions()

int bdlmt::Throttle::maxSimultaneousActions ( ) const

inline

Return the maximum number of simultaneous actions for which this Throttle is configured to permit.

nanosecondsPerAction()

bsls::Types::Int64 bdlmt::Throttle::nanosecondsPerAction ( ) const

inline

Return the time debt, in nanoseconds, that this Throttle is configured to incur for each action permitted.

nextPermit()

int bdlmt::Throttle::nextPermit	(	bsls::TimeInterval *	result,
		int	numActions
	)		const

Load into the specified result the earliest absolute time (according to system clock configured at initialization) when the specified numActions will next be permitted. Return 0 on success, and a non-zero value (with no effect on result) if this throttle is configured such that numActions will never be permitted (i.e., return an error if numActions > maxSimultaneousActions) or if numActions <= 0. The returned result is an offset from the epoch of the system clock for which this throttle is configured. The behavior is undefined unless this throttle has been initialized (either by calling initialize or using a BDLMT_THROTTLE_INIT* macro). Note that result may be in the past, and this function does not obtain the current time from the system clock.

requestPermission() [1/4]

bool bdlmt::Throttle::requestPermission ( )

inline

requestPermission() [2/4]

bool bdlmt::Throttle::requestPermission

(

const bsls::TimeInterval &

now

)

requestPermission() [3/4]

bool bdlmt::Throttle::requestPermission ( int  numActions )

inline

requestPermission() [4/4]

bool bdlmt::Throttle::requestPermission	(	int	numActions,
		const bsls::TimeInterval &	now
	)

Return true if the time debt incurred by taking the indicated action(s) would not exceed the maximum allowed time debt configured for this Throttle object (nanosecondsPerAction * maxSimultaneousActions), and false otherwise. Optionally specify now indicating the current time of the system clock for which this object is configured (now is a offset from that clocks epoch). If now is not supplied, the current time is obtained from the configured system clock. Optionally specify numActions indicating the number of actions requested. If numActions is not supplied, one action is requested. If this function returns true then numActions * nanosecondsPerAction is added to the time debt accumulated by this component. The behavior is undefined unless this throttle has been initialized (either by calling an overload of initialize or using one of the BDLMT_THROTTLE_INIT* macros), 0 < numActions, (numActions <= maxSimultaneousActions or 0 == maxSimultaneousActions), and the value of now, if specified, can be expressed in nanoseconds as a 64-bit signed integer. Note that requestPermissionIfValid, unlike these methods, does not have any preconditions on the value of numActions.

requestPermissionIfValid() [1/2]

int bdlmt::Throttle::requestPermissionIfValid ( bool *  result, int  numActions  )

inline

requestPermissionIfValid() [2/2]

int bdlmt::Throttle::requestPermissionIfValid	(	bool *	result,
		int	numActions,
		const bsls::TimeInterval &	now
	)

Set the specified *result to true if the time debt incurred by taking the specified numActions would not exceed the maximum allowed time debt configured for this Throttle object (nanosecondsPerAction * maxSimultaneousActions), and set *result to false otherwise. Optionally specify now indicating the current time of the system clock for which this object is configured (now is a offset from that clocks epoch). If now is not supplied, the current time is obtained from the configured system clock. If *result is set to true then numActions * nanosecondsPerAction is added to the time debt accumulated by this component. Return 0 if 0 <= numActions, (numActions <= maxSimultaneousActions or 0 == maxSimultaneousActions), and the value of now, if specified, can be expressed in nanoseconds as a 64-bit signed integer, and a non-zero value otherwise. The behavior is undefined unless this throttle has been initialized (either by calling an overload of initialize or using one of the BDLMT_THROTTLE_INIT* macros). Note that unless 0 is returned, *result is unaffected.

Friends And Related Symbol Documentation

Throttle_InitHelper

template<int t_MAX_SIMULTANEOUS_ACTIONS, bsls::Types::Int64 t_NANOSECONDS_PER_ACTION>

friend class Throttle_InitHelper

friend

Member Data Documentation

d_clockType

bsls::SystemClockType::Enum bdlmt::Throttle::d_clockType

d_maxSimultaneousActions

int bdlmt::Throttle::d_maxSimultaneousActions

d_nanosecondsPerAction

Int64 bdlmt::Throttle::d_nanosecondsPerAction

d_nanosecondsPerTotalReset

Int64 bdlmt::Throttle::d_nanosecondsPerTotalReset

d_prevLeakTime

AtomicTypes::Int64 bdlmt::Throttle::d_prevLeakTime

k_TEN_YEARS_NANOSECONDS

const Int64 bdlmt::Throttle::k_TEN_YEARS_NANOSECONDS

static

Initial value:

= 10 * 366 *
                                    bdlt::TimeUnitRatio::k_NANOSECONDS_PER_DAY

---

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

• bdlmt_throttle.h