Token bucket counter template. More...

#include <click/tokenbucket.hh>

Public Types
enum	{ max_tokens = R::max_tokens }

typedef R	rate_type
	The token rate type.

typedef R::token_type	token_type
	Unsigned type of token counts.

typedef R::time_point_type	time_point_type
	Type of time points.

typedef R::ticks_type	ticks_type
	Unsigned type of tick counts (differences between time points).

Public Member Functions
	TokenCounterX ()
	Construct an empty TokenCounter.

	TokenCounterX (bool full)
	Construct a TokenCounter.

token_type	size (const rate_type &rate) const
	Return the number of tokens in the counter.

token_type	fraction () const
	Return the counter's fullness fraction.

bool	empty () const
	Test if the token counter is completely empty.

bool	full () const
	Test if the token counter is at full capacity.

bool	contains (const rate_type &rate, token_type t) const
	Test if the token counter has at least t tokens.

bool	contains_fraction (token_type f) const
	Test if the token counter is above a fraction of its capacity.

void	clear ()
	Clear the token counter.

void	set_full ()
	Fill the token counter to capacity.

void	set (const rate_type &rate, token_type t)
	Set the token counter to contain t tokens.

void	set_fraction (token_type f)
	Set the token counter to a fraction of its capacity.

void	adjust (const rate_type &old_rate, const rate_type &new_rate)
	Compensate the counter for a change of rate.

void	refill (const rate_type &rate)
	Refill the token counter to time rate.now().

void	refill (const rate_type &rate, time_point_type time)
	Refill the token counter for time.

template<typename U >
void	refill (const rate_type &rate, U time)
	Refill the token counter for time.

void	set_time_point (time_point_type time)
	Set the token counter's internal time point to time.

time_point_type	time_point ()
	Return the internal time point.

void	remove (const rate_type &rate, token_type t)
	Remove t tokens from the counter.

bool	remove_if (const rate_type &rate, token_type t)
	Remove t tokens from the counter if it contains t tokens.

void	remove_fraction (token_type f)
	Remove a fullness fraction from the counter.

bool	remove_fraction_if (token_type f)
	Remove a fullness fraction from the counter if it is full enough.

ticks_type	time_until_contains (const rate_type &rate, token_type t) const
	Return the number of ticks until contains(rate, t).

ticks_type	time_until_contains_fraction (const rate_type &rate, token_type f) const
	Return the number of ticks until contains_fraction(f).

Detailed Description

template<typename R>
class TokenCounterX< R >

Token bucket counter template.

never never

The TokenCounterX class implements a token counter associated with a token bucket rate. The rate type, normally a TokenRateX, is specified as a template parameter. Most of its member functions take an explicit rate argument. The contains() method reports whether the counter has at least a given number of tokens. The counter is emptied by the remove() and remove_if() methods and refilled by the refill() methods.

Often the token rate associated with a counter will not change during the counter's lifetime. TokenCounterX will work correctly if the rate changes, however. (See the adjust() method for details.)

TokenCounterX internally maintains fractional tokens, so it should be relatively precise.

Idle and unlimited rates affect how TokenCounters are refilled. For idle rates, refill() is a no-op. For unlimited rates, any refill() makes the counter full(), containing max_tokens tokens. The set(), empty(), full(), remove(), and similar functions act as normal for idle and unlimited rates.

Most users will be satisfied with the TokenCounter type, which is equal to TokenCounterX<TokenRateX<TokenBucketUsecParameters<unsigned long long> > >.

See also: TokenRateX, TokenBucketX

Member Typedef Documentation

◆ rate_type

template<typename R >

typedef R TokenCounterX< R >::rate_type

The token rate type.

◆ token_type

template<typename R >

typedef R::token_type TokenCounterX< R >::token_type

Unsigned type of token counts.

◆ time_point_type

template<typename R >

typedef R::time_point_type TokenCounterX< R >::time_point_type

Type of time points.

◆ ticks_type

template<typename R >

typedef R::ticks_type TokenCounterX< R >::ticks_type

Unsigned type of tick counts (differences between time points).

Constructor & Destructor Documentation

◆ TokenCounterX() [1/2]

template<typename R >

TokenCounterX< R >::TokenCounterX ( )

inline

Construct an empty TokenCounter.

The initial time point is 0.

◆ TokenCounterX() [2/2]

template<typename R >

TokenCounterX< R >::TokenCounterX ( bool full )

inlineexplicit

Construct a TokenCounter.

Parameters

full	whether the counter is created full

The counter is initially full() if full is true, otherwise it is empty. The initial time point is 0.

Member Function Documentation

◆ size()

template<typename R >

token_type TokenCounterX< R >::size ( const rate_type & rate ) const

inline

Return the number of tokens in the counter.

Parameters

rate	associated token rate

The return value is a lower bound on the number of tokens, since TokenCounterX keeps track of fractional tokens.

◆ fraction()

template<typename R >

token_type TokenCounterX< R >::fraction ( ) const

inline

Return the counter's fullness fraction.

The return value is a number between 0 and max_tokens, where max_tokens represents full capacity.

◆ empty()

template<typename R >

bool TokenCounterX< R >::empty ( ) const

inline

Test if the token counter is completely empty.

◆ full()

template<typename R >

bool TokenCounterX< R >::full ( ) const

inline

Test if the token counter is at full capacity.

◆ contains()

template<typename R >

bool TokenCounterX< R >::contains	(	const rate_type &	rate,
		token_type	t
	)		const

inline

Test if the token counter has at least t tokens.

Parameters

rate	associated token rate
t	token count

Returns false whenever t is greater than rate.capacity().

◆ contains_fraction()

template<typename R >

bool TokenCounterX< R >::contains_fraction ( token_type f ) const

inline

Test if the token counter is above a fraction of its capacity.

Parameters

f	fullness fraction, where max_tokens is full capacity

◆ clear()

template<typename R >

void TokenCounterX< R >::clear ( )

inline

Clear the token counter.

See also: set(), set_full()

◆ set_full()

template<typename R >

void TokenCounterX< R >::set_full ( )

inline

Fill the token counter to capacity.

See also: clear(), set()

◆ set()

template<typename R >

void TokenCounterX< R >::set	(	const rate_type &	rate,
		token_type	t
	)

inline

Set the token counter to contain t tokens.

Parameters

rate	associated token rate
t	number of tokens

The result will never have more tokens than the associated capacity.

◆ set_fraction()

template<typename R >

void TokenCounterX< R >::set_fraction ( token_type f )

inline

Set the token counter to a fraction of its capacity.

Parameters

f	fullness fraction, where max_tokens is full capacity

◆ adjust()

template<typename R >

void TokenCounterX< R >::adjust	(	const rate_type &	old_rate,
		const rate_type &	new_rate
	)

inline

Compensate the counter for a change of rate.

Parameters

old_rate	old associated token rate
new_rate	new associated token rate

TokenCounterX's internal representation stores the token count as a fraction of the rate's capacity. This means that if you change the associated rate to have a different capacity, the token count will appear to change. To keep the token count roughly the same, call adjust() with the old and new rates; TokenCounterX will as far as possible compensate for the rate change.

◆ refill() [1/3]

template<typename R >

void TokenCounterX< R >::refill ( const rate_type & rate )

Refill the token counter to time rate.now().

Parameters

rate	associated token rate

There are three refill() methods, useful for different methods of measuring time. This method calls rate.now(), which returns the current time. Other methods use an explicit time point and a rate.time_point(U) method.

See also: set_time_point

◆ refill() [2/3]

template<typename R >

void TokenCounterX< R >::refill	(	const rate_type &	rate,
		time_point_type	time
	)

Refill the token counter for time.

Parameters

rate	associated token rate
time	new time point

◆ refill() [3/3]

template<typename R >

template<typename U >

void TokenCounterX< R >::refill	(	const rate_type &	rate,
		U	time
	)

Refill the token counter for time.

Parameters

rate	associated token rate
time	new time

◆ set_time_point()

template<typename R >

void TokenCounterX< R >::set_time_point ( time_point_type time )

inline

Set the token counter's internal time point to time.

Parameters

time	new time point

Unlike refill(), this method does not refill the counter.

See also: refill

◆ time_point()

template<typename R >

time_point_type TokenCounterX< R >::time_point ( )

inline

Return the internal time point.

Returns: time point

See also: refill

◆ remove()

template<typename R >

void TokenCounterX< R >::remove	(	const rate_type &	rate,
		token_type	t
	)

inline

Remove t tokens from the counter.

Parameters

rate	associated token rate
t	number of tokens

If the token counter contains less than t tokens, the new token count is 0.

◆ remove_if()

template<typename R >

bool TokenCounterX< R >::remove_if	(	const rate_type &	rate,
		token_type	t
	)

inline

Remove t tokens from the counter if it contains t tokens.

Parameters

rate	associated token rate
t	number of tokens

Returns: true if t tokens were removed, false otherwise

If the counter contains t or more tokens, calls remove(t) and returns true. If it contains less than t tokens, returns false without removing any tokens.

◆ remove_fraction()

template<typename R >

void TokenCounterX< R >::remove_fraction ( token_type f )

inline

Remove a fullness fraction from the counter.

Parameters

f	fullness fraction, where max_tokens is full capacity

If the token counter is less than f full, the new token count is 0.

◆ remove_fraction_if()

template<typename R >

bool TokenCounterX< R >::remove_fraction_if ( token_type f )

inline

Remove a fullness fraction from the counter if it is full enough.

Parameters

f	fullness fraction, where max_tokens is full capacity

Returns: true if f was removed, false otherwise

If fraction() is at least f, calls remove_fraction(f) and returns true. Otherwise, returns false without removing any tokens.

◆ time_until_contains()

template<typename R >

ticks_type TokenCounterX< R >::time_until_contains	(	const rate_type &	rate,
		token_type	t
	)		const

inline

Return the number of ticks until contains(rate, t).

Parameters

rate	associated token rate
t	token count

Returns (ticks_type) -1 if passing time will never make contains(rate, t) true.

◆ time_until_contains_fraction()

template<typename R >

ticks_type TokenCounterX< R >::time_until_contains_fraction	(	const rate_type &	rate,
		token_type	f
	)		const

inline

Return the number of ticks until contains_fraction(f).

Parameters

rate	associated token rate
f	fullness fraction, where max_tokens is full capacity

Returns (ticks_type) -1 if passing time will never make contains_fraction(f) true.

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

include/click/tokenbucket.hh

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ rate_type

◆ token_type

◆ time_point_type

◆ ticks_type

Constructor & Destructor Documentation

◆ TokenCounterX() [1/2]

◆ TokenCounterX() [2/2]

Member Function Documentation

◆ size()

◆ fraction()

◆ empty()

◆ full()

◆ contains()

◆ contains_fraction()

◆ clear()

◆ set_full()

◆ set()

◆ set_fraction()

◆ adjust()

◆ refill() [1/3]

◆ refill() [2/3]

◆ refill() [3/3]

◆ set_time_point()

◆ time_point()

◆ remove()

◆ remove_if()

◆ remove_fraction()

◆ remove_fraction_if()

◆ time_until_contains()

◆ time_until_contains_fraction()