A timer which can detect timeouts. More...

#include <timeout_timer.hpp>

Collaboration diagram for agentxcpp::timeout_timer:

Public Types
enum	status_t { running, expired, standby, broken }
	The timeout status type. More...

Public Member Functions
	timeout_timer (boost::asio::io_service &io_service)
	Constructor.
void	expires_at (boost::asio::deadline_timer::time_type time)
	Time out at the given time.
void	expires_from_now (boost::asio::deadline_timer::duration_type duration)
	Time out at (now + duration).
void	cancel ()
	Stop the timer.
status_t	get_status ()
	Get the current timer status.
	~timeout_timer ()
	Destructor.

Private Member Functions
	timeout_timer ()
	Hide default constructor.

Static Private Member Functions
static void	check_deadline (timeout_timer *self)
	The timeout handler.

Private Attributes
status_t	status
	The timeout status.
boost::asio::deadline_timer	timer
	The boost::asio timer.

Static Private Attributes
static std::set< timeout_timer * >	available_timers
	Set of timeout_timer objects currently in existence.

Detailed Description

A timer which can detect timeouts.

This timer can detect timeouts. A timeout_timer object starts in "standby" state. The timer can then be started using the expires_at() (giving an absolute time) or expires_from_now() (giving a time span) methods, which changes the status to "running". When the timer expires, the status changes to "expired". The timer can be disabled at any time using cancel(), which changes the status back to "standby" (this works also with an expired timer).

This class uses the boost::asio library and therefore needs an io_service object. It never calls io_service::run() or io_service::run_one(). For the timeout_timer to work, the run() or run_one() method of the io_service object must be invoked by the user of timeout_timer. As long as neither of them are invoked, the timer will not report the status "expired".

The object can break, e.g. when something with the interally used boost::asio::deadline_timer goes wrong. In this case the status changes to "broken". A broken timeout_timer cannot be used anymore: a call to any member function will do nothing (except for get_status(), which will report the status "broken") and the status will be "broken" forever.

How it works

For timeout detection, an asio deadline_timer is used together with the status member. While the timer is not in use, it's expiry time is set to "infinite" and status is set to "standby". When starting the timer, the deadline_timer's expiry is set to the according time, and status is set to "running". If the deadline_timer expires, it invokes the check_deadline() callback, which sets the expiry back to "infinite" and status to "expired". If cancel() is invoked before the deadline_timer expires, the expiry is set back to "infinite" and the status to "standby".

The check_deadline() callback may be invoked errornously, e.g. when the deadline_timer's expiry time is reset after the timer expired, but before the callback actually is invoked. Therefore, check_deadline() compares the expiry date of the timer with the current timestamp to determine whether the timer really expired.

Also, check_deadline() is called after the deadline_timer object is destroyed. This happens when a timeout_timer object is destroyed, which means that the callback function must not be a member function. Instead it is a static class function which takes a pointer to the timeout_timer object for which it is called. To identify calls for destroyed objects, the static mamber "available_timers" is used, which stores pointers to all timeout_timer objects currently in existence. This is handled by the constructors and destructor of the timeout_timer class.

Definition at line 81 of file timeout_timer.hpp.

Member Enumeration Documentation

enum agentxcpp::timeout_timer::status_t

The timeout status type.

Enumerator:

running
expired
standby
broken

Definition at line 104 of file timeout_timer.hpp.

Constructor & Destructor Documentation

timeout_timer::timeout_timer ( boost::asio::io_service & io_service )

Constructor.

This constructor sets the timer status to "standby", the deadline_timer's expiry to "infinite" and add the new object to "available_timers". It also starts the deadline_timer.

Note:: If something goes wrong, the status is set to "broken".

Parameters:

io_service The io_service object which will be used by the timer.

Exceptions:

None.

Definition at line 30 of file timeout_timer.cpp.

References available_timers, broken, check_deadline(), status, and timer.

timeout_timer::~timeout_timer ( )

Destructor.

The destructor removes the object from "available_timers".

Definition at line 172 of file timeout_timer.cpp.

References available_timers.

agentxcpp::timeout_timer::timeout_timer ( )

private

Hide default constructor.

We need an io_service object to function properly.

Member Function Documentation

void timeout_timer::cancel ( )

Stop the timer.

This stops the timer. The status is set to "standby", and the deadline_timer's expiry time is set to "infinite".

Note:: If something goes wrong, the status is set to "broken".

Exceptions:

None.

Definition at line 149 of file timeout_timer.cpp.

References broken, standby, status, and timer.

void timeout_timer::check_deadline ( timeout_timer * self )

staticprivate

The timeout handler.

This function is used as callback handler for 'timer'. It compares the deadline_timer's expiry time with the current system time to detect errornous invokation. It also checks whether the timeout_timer object exists (and does nothing if not). If a real timeout is detected, the status is set to "expired" and the deadline_timer's expiry is set to "infinite".

This callback also restarts the timer on each call to keep it running.

If something goes wrong, the status is set to "broken".

Parameters:

self	The timeout_timer object which triggered the callback.

Definition at line 100 of file timeout_timer.cpp.

References broken, and expired.

Referenced by timeout_timer().

void timeout_timer::expires_at ( boost::asio::deadline_timer::time_type time )

Time out at the given time.

This function starts the timer and set its expiry time to 'time'. The status is set to 'running'.

Note:: If something goes wrong, the status is set to "broken".

Parameters:

time	The time at which the timer shall expire.

Exceptions:

None.

Definition at line 52 of file timeout_timer.cpp.

References broken, running, status, and timer.

void timeout_timer::expires_from_now ( boost::asio::deadline_timer::duration_type duration )

Time out at (now + duration).

This function starts the deadline_timer and sets its expiry time to (now + 'duration'). The status is set to 'running'.

Note:: If something goes wrong, the status is set to "broken".

Parameters:

duration The duration after which the timer elapses.

Exceptions:

None.

Definition at line 76 of file timeout_timer.cpp.

References broken, running, status, and timer.

status_t agentxcpp::timeout_timer::get_status ( )

inline

Get the current timer status.

Exceptions:

None.

Definition at line 157 of file timeout_timer.hpp.

References status.

Member Data Documentation

std::set< timeout_timer * > timeout_timer::available_timers

staticprivate

Set of timeout_timer objects currently in existence.

Definition at line 174 of file timeout_timer.hpp.

Referenced by timeout_timer(), and ~timeout_timer().

status_t agentxcpp::timeout_timer::status

private

The timeout status.

Definition at line 186 of file timeout_timer.hpp.

Referenced by cancel(), expires_at(), expires_from_now(), get_status(), and timeout_timer().

boost::asio::deadline_timer agentxcpp::timeout_timer::timer

private

The boost::asio timer.

This timer is used to detect timeout conditions.

Definition at line 193 of file timeout_timer.hpp.

Referenced by cancel(), expires_at(), expires_from_now(), and timeout_timer().

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

/home/tanjeff/projekte/agentxcpp/agentXcpp-0.1.1/src/timeout_timer.hpp
/home/tanjeff/projekte/agentxcpp/agentXcpp-0.1.1/src/timeout_timer.cpp

Public Types

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation