Token bucket rate limiter. More...

#include <click/tokenbucket.hh>

Public Types
enum	{ max_tokens = rate_type::max_tokens }

typedef P	parameter_type
	The template parameter type.

typedef TokenRateX< P >	rate_type
	The token rate type.

typedef TokenCounterX< rate_type >	counter_type
	The token counter type.

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

typedef rate_type::time_point_type	time_point_type
	Type of time ticks.

typedef rate_type::ticks_type	ticks_type
	Unsigned type of differences between time ticks.

Public Member Functions
	TokenBucketX ()
	Construct an idle token bucket.

	TokenBucketX (bool unlimited)
	Construct an idle or unlimited token bucket.

	TokenBucketX (token_type rate, token_type capacity)
	Construct a token bucket representing rate.

void	assign (bool unlimited=false)
	Set the token bucket rate to idle or unlimited.

void	assign (token_type rate, token_type capacity)
	Set the token bucket rate and capacity.

void	assign_adjust (token_type rate, token_type capacity)
	Set the token bucket rate and capacity, preserving the token count.

bool	unlimited () const
	Return true iff the token rate is unlimited.

bool	idle () const
	Return true iff the token rate is idle.

token_type	rate () const
	Return the rate in tokens per period.

token_type	capacity () const
	Return the capacity in tokens.

token_type	size () const
	Return the number of tokens in the bucket.

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

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

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

bool	contains (token_type t) const
	Test if the token bucket has at least t tokens.

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

void	clear ()
	Clear the token bucket.

void	set_full ()
	Fill the token bucket to capacity.

void	set (token_type t)
	Set the token bucket to contain t tokens.

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

void	refill ()
	Refill the token bucket to time P::now().

void	refill (time_point_type time)
	Refill the token bucket for time.

template<typename U >
void	refill (U time)
	Refill the token bucket for time P::time_point(time).

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

time_point_type	time_point ()

void	remove (token_type t)
	Remove t tokens from the bucket.

bool	remove_if (token_type t)
	Remove t tokens from the bucket if it contains t tokens.

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

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

ticks_type	time_until_contains (token_type t) const
	Return the number of ticks until contains(t).

ticks_type	time_until_contains_fraction (ticks_type f) const
	Return the number of ticks until contains_fraction(f).

Detailed Description

template<typename P>
class TokenBucketX

Token bucket rate limiter.

The TokenBucketX class implements a token bucket rate limiter. It is implemented as a pair of TokenRateX and TokenCounterX.

Most users will be satisfied with the TokenBucket type, which is equal to TokenBucketX<TokenBucketUsecParameters<unsigned long long> >.

See also: GapRate

Member Typedef Documentation

◆ parameter_type

template<typename P >

typedef P TokenBucketX::parameter_type

The template parameter type.

◆ rate_type

template<typename P >

typedef TokenRateX TokenBucketX::rate_type

The token rate type.

◆ counter_type

template<typename P >

typedef TokenCounterX<rate_type> TokenBucketX::counter_type

The token counter type.

◆ token_type

template<typename P >

typedef rate_type::token_type TokenBucketX::token_type

Unsigned type of token counts.

◆ time_point_type

template<typename P >

typedef rate_type::time_point_type TokenBucketX::time_point_type

Type of time ticks.

◆ ticks_type

template<typename P >

typedef rate_type::ticks_type TokenBucketX::ticks_type

Unsigned type of differences between time ticks.

Constructor & Destructor Documentation

◆ TokenBucketX() [1/3]

template<typename P >

TokenBucketX::TokenBucketX ( )

inline

Construct an idle token bucket.

The initial time point is 0.

◆ TokenBucketX() [2/3]

template<typename P >

TokenBucketX::TokenBucketX ( bool unlimited )

inlineexplicit

Construct an idle or unlimited token bucket.

Parameters

unlimited idle if false, unlimited if true

The initial time point is 0.

◆ TokenBucketX() [3/3]

template<typename P >

TokenBucketX< P >::TokenBucketX	(	token_type	rate,
		token_type	capacity
	)

inline

Construct a token bucket representing rate.

Parameters

rate	refill rate in tokens per period
capacity	maximum token accumulation

The initial time point is 0 and the token bucket is initially full (the initial token count equals capacity). The rate is idle if either rate or capacity is 0.

See also: assign(rate, capacity)

Member Function Documentation

◆ assign() [1/2]

template<typename P >

void TokenBucketX::assign ( bool unlimited = false )

inline

Set the token bucket rate to idle or unlimited.

Parameters

unlimited idle if false, unlimited if true

◆ assign() [2/2]

template<typename P >

void TokenBucketX< P >::assign	(	token_type	rate,
		token_type	capacity
	)

inline

Set the token bucket rate and capacity.

Parameters

rate	refill rate in tokens per period
capacity	maximum token accumulation

Sets the token bucket's rate to rate and capacity to capacity. If either rate or capacity is 0, the token bucket becomes idle. The time point is unchanged.

The ratio of tokens/burst is unchanged by the assignment, so the actual number of tokens could go up or down, depending on how the rate is changed.

See also: assign_adjust

◆ assign_adjust()

template<typename P >

void TokenBucketX< P >::assign_adjust	(	token_type	rate,
		token_type	capacity
	)

inline

Set the token bucket rate and capacity, preserving the token count.

Parameters

rate	refill rate in tokens per period
capacity	maximum token accumulation

This performs the same function as assign(), but additionally keeps the number of tokens roughly stable.

See also: assign

◆ unlimited()

template<typename P >

bool TokenBucketX::unlimited ( ) const

inline

Return true iff the token rate is unlimited.

◆ idle()

template<typename P >

bool TokenBucketX::idle ( ) const

inline

Return true iff the token rate is idle.

◆ rate()

template<typename P >

token_type TokenBucketX::rate ( ) const

inline

Return the rate in tokens per period.

Returns max_tokens for unlimited rates. Imprecise computer arithmetic may cause the result to differ from the configured rate.

◆ capacity()

template<typename P >

token_type TokenBucketX::capacity ( ) const

inline

Return the capacity in tokens.

Returns max_tokens for unlimited rates. Imprecise computer arithmetic may cause the result to differ from the configured capacity.

◆ size()

template<typename P >

token_type TokenBucketX::size ( ) const

inline

Return the number of tokens in the bucket.

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

◆ fraction()

template<typename P >

token_type TokenBucketX::fraction ( ) const

inline

Return the bucket's fullness fraction.

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

◆ empty()

template<typename P >

bool TokenBucketX::empty ( ) const

inline

Test if the token bucket is completely empty.

◆ full()

template<typename P >

bool TokenBucketX::full ( ) const

inline

Test if the token bucket is at full capacity.

◆ contains()

template<typename P >

bool TokenBucketX::contains ( token_type t ) const

inline

Test if the token bucket has at least t tokens.

Returns true whenever t is zero or rate is unlimited. Returns false whenever t is greater than rate.capacity().

◆ contains_fraction()

template<typename P >

bool TokenBucketX::contains_fraction ( token_type f ) const

inline

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

Parameters

f	fullness fraction, where max_tokens is full capacity

◆ clear()

template<typename P >

void TokenBucketX::clear ( )

inline

Clear the token bucket.

See also: set(), set_full()

◆ set_full()

template<typename P >

void TokenBucketX::set_full ( )

inline

Fill the token bucket to capacity.

See also: clear(), set()

◆ set()

template<typename P >

void TokenBucketX::set ( token_type t )

inline

Set the token bucket to contain t tokens.

Parameters

t	number of tokens

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

◆ set_fraction()

template<typename P >

void TokenBucketX::set_fraction ( token_type f )

inline

Set the token bucket to a fraction of its capacity.

Parameters

f	fullness fraction, where max_tokens is full capacity

◆ refill() [1/3]

template<typename P >

void TokenBucketX::refill ( )

inline

Refill the token bucket to time P::now().

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

See also: set_time_point

◆ refill() [2/3]

template<typename P >

void TokenBucketX::refill ( time_point_type time )

inline

Refill the token bucket for time.

◆ refill() [3/3]

template<typename P >

template<typename U >

void TokenBucketX::refill ( U time )

inline

Refill the token bucket for time P::time_point(time).

◆ set_time_point()

template<typename P >

void TokenBucketX::set_time_point ( time_point_type time )

inline

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

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

See also: refill

◆ remove()

template<typename P >

void TokenBucketX::remove ( token_type t )

inline

Remove t tokens from the bucket.

Parameters

t	number of tokens

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

◆ remove_if()

template<typename P >

bool TokenBucketX::remove_if ( token_type t )

inline

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

Parameters

t	number of tokens

Returns: true if t tokens were removed, false otherwise

If the token bucket 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 P >

void TokenBucketX::remove_fraction ( token_type f )

inline

Remove a fullness fraction from the bucket.

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 P >

bool TokenBucketX::remove_fraction_if ( token_type f )

inline

Remove a fullness fraction from the bucket 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 P >

ticks_type TokenBucketX::time_until_contains ( token_type t ) const

inline

Return the number of ticks until contains(t).

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

◆ time_until_contains_fraction()

template<typename P >

ticks_type TokenBucketX::time_until_contains_fraction ( ticks_type f ) const

inline

Return the number of ticks until contains_fraction(f).

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

◆ parameter_type

◆ rate_type

◆ counter_type

◆ token_type

◆ time_point_type

◆ ticks_type

Constructor & Destructor Documentation

◆ TokenBucketX() [1/3]

◆ TokenBucketX() [2/3]

◆ TokenBucketX() [3/3]

Member Function Documentation

◆ assign() [1/2]

◆ assign() [2/2]

◆ assign_adjust()

◆ unlimited()

◆ idle()

◆ rate()

◆ capacity()

◆ size()

◆ fraction()

◆ empty()

◆ full()

◆ contains()

◆ contains_fraction()

◆ clear()

◆ set_full()

◆ set()

◆ set_fraction()

◆ refill() [1/3]

◆ refill() [2/3]

◆ refill() [3/3]

◆ set_time_point()

◆ remove()

◆ remove_if()

◆ remove_fraction()

◆ remove_fraction_if()

◆ time_until_contains()

◆ time_until_contains_fraction()