GapRate Class Reference

A helper class for implementing a uniform rate. More...

#include <click/gaprate.hh>

Public Types
enum	{ UGAP_SHIFT = 43 }
enum	{ MAX_RATE = 1000000ULL << UGAP_SHIFT }

Public Member Functions
	GapRate ()
	Construct a GapRate object with initial rate 0.
	GapRate (uint64_t r)
	Construct a GapRate object with initial rate r.
uint64_t	rate () const
	Return the current rate.
void	set_rate (uint64_t r)
	Set the current rate to r.
void	set_rate (uint64_t r, ErrorHandler *errh)
	Set the current rate to r.
bool	need_update (const Timestamp &ts)
	Returns whether the user's rate is behind the true rate.
Timestamp	expiry () const
	Returns a time when the user's rate will be behind the true rate.
void	update ()
	Increment the user event counter.
void	update_with (int64_t delta)
	Increment the user event counter by delta.
void	reset ()
	Resets the true rate counter.

Detailed Description

A helper class for implementing a uniform rate.

The GapRate class helps its user implement a process with a uniform rate: a process in which one user event happens every T seconds. GapRate is designed to efficiently model high rates. (Contrast this with Timer, which can serve a similar function at low rates.)

GapRate is not a great choice for limiting the rates of external processes. See TokenBucketX, a token bucket rate limiter.

GapRate models an underlying "true" rated process with the correct rate. It also keeps a counter, maintained by its user via the update() method, that measures the progress of the user's rated process. The needs_update() method compares this counter with its expected value, which is determined by the true rated process. If the user's rated process is running behind, then needs_update() returns true; the user should trigger an event and call the update() method. If the user's rated process is just right or is running faster than the true process, then needs_update() returns false; the user should not trigger an event.

Creating a non-bursty rate can be expensive and difficult. GapRate attempts to create a non-bursty rate using timestamps and some interesting microsecond-based arithmetic. External factors can cause scheduling hiccups where GapRate is not called as much as expected. GapRate compensates for hiccups: the user's rated process may fall up to a full second behind the true rated process, then catch up in a burst. More than one second's worth of lag is ignored.

The maximum rate GapRate can implement is MAX_RATE events per second.

See also

TokenBucketX, Timer

Constructor & Destructor Documentation

GapRate() [1/2]

GapRate::GapRate ( )

inline

Construct a GapRate object with initial rate 0.

GapRate() [2/2]

GapRate::GapRate ( uint64_t  r )

inline

Construct a GapRate object with initial rate r.

Parameters

r	initial rate (events per second)

Member Function Documentation

rate()

uint64_t GapRate::rate ( ) const

inline

Return the current rate.

set_rate() [1/2]

void GapRate::set_rate ( uint64_t  r )

inline

Set the current rate to r.

Parameters

r	desired rate (events per second)

Rates larger than MAX_RATE are reduced to MAX_RATE. Also performs the equivalent of a reset() to flush old state.

set_rate() [2/2]

void GapRate::set_rate	(	uint64_t	r,
		ErrorHandler *	errh
	)

Set the current rate to r.

Parameters

r	desired rate (events per second)
errh	error handler

Acts like set_rate(r), except that an warning is reported to errh if r is larger than MAX_RATE.

need_update()

bool GapRate::need_update ( const Timestamp &  ts )

inline

Returns whether the user's rate is behind the true rate.

Parameters

ts	current timestamp

Returns true iff the user's rate is currently behind the true rate, meaning the user should cause an event and call update().

expiry()

Timestamp GapRate::expiry ( ) const

inline

Returns a time when the user's rate will be behind the true rate.

Precondition

need_update() has been called at least once.

Returns

If the rate is 0, or need_update() has not been called, returns Timestamp(). If the user's rate is already behind the true rate, returns a time no greater than the argument passed to the last need_update(). Otherwise, returns a time in the future when need_update() will return true.

update()

void GapRate::update ( )

inline

Increment the user event counter.

Call this function when causing a user event.

update_with()

void GapRate::update_with ( int64_t  delta )

inline

Increment the user event counter by delta.

Parameters

delta

number of user events

Note

This may be faster than calling update() delta times. Furthermore, delta can be negative.

reset()

void GapRate::reset ( )

inline

Resets the true rate counter.

Reset the underlying rated process.

This function flushes any old information about the true rate counter and its relationship to the user's rate counter.

---

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

• include/click/gaprate.hh
• lib/gaprate.cc