E-MailRelay
|
A singleton which maintains a list of all Timer objects, and interfaces to the event loop on their behalf. More...
#include <gtimerlist.h>
Public Member Functions | |
TimerList () | |
Default constructor. More... | |
~TimerList () | |
Destructor. More... | |
void | add (TimerBase &, ExceptionSink) |
Adds a timer. Called from the Timer constructor. More... | |
void | remove (TimerBase &) noexcept |
Removes a timer from the list. More... | |
void | updateOnStart (TimerBase &) |
Called by Timer when a timer is started. More... | |
void | updateOnCancel (TimerBase &) |
Called by Timer when a timer is cancelled. More... | |
std::pair< G::TimeInterval, bool > | interval () const |
Returns the interval to the first timer expiry. More... | |
void | doTimeouts () |
Triggers the timeout callbacks of any expired timers. More... | |
std::string | report () const |
Returns a line of text reporting the status of the timer list. More... | |
void | disarm (ExceptionHandler *) noexcept |
Resets any matching ExceptionHandler pointers. More... | |
TimerList (const TimerList &)=delete | |
TimerList (TimerList &&)=delete | |
void | operator= (const TimerList &)=delete |
void | operator= (TimerList &&)=delete |
Static Public Member Functions | |
static bool | exists () |
Returns true if instance() exists. More... | |
static TimerList * | ptr () noexcept |
Singleton access. Returns nullptr if none. More... | |
static TimerList & | instance () |
Singleton access. Throws an exception if none. More... | |
Friends | |
class | GNet::TimerListTest |
struct | Lock |
A singleton which maintains a list of all Timer objects, and interfaces to the event loop on their behalf.
Event loops should call TimerList::interval() to determine how long to wait before the first Timer goes off. If the timed-wait times-out or if the interval was zero then they must call TimerList::doTimeouts().
There can be a race where this class incorrectly sees no expired timers in doTimeouts() if, for example, the system clock is being stretched. However, the interval() or setTimer() time will be very small and the race will resolve itself naturally.
Every timer has an associated exception handler, typically a more long-lived object that has the timer as a sub-object. If the timer callback throws an exception then timer list catches it and invokes the exception handler – and if that throws then the exception escapes the event loop. This is safe even if the exception handler object is destroyed by the original exception because the exception handler base-class destructor uses the timer list's disarm() mechanism. This is the same behaviour as in the EventHandlerList.
Exception handlers are combined with an additional 'source' pointer in an ExceptionSink tuple. The source pointer can be used to provide additional information to the exception handler, typically as a pointer to the event handler (sic) object.
The implementation maintains a pointer to the timer that will expire soonest so that interval() is fast and O(1) when the set of timers is stable and most events are non-timer events.
Zero-length timers expire in the same order as they were started, which allows them to be used as a mechanism for asynchronous message-passing.
Definition at line 75 of file gtimerlist.h.
GNet::TimerList::TimerList | ( | ) |
Default constructor.
Definition at line 76 of file gtimerlist.cpp.
GNet::TimerList::~TimerList | ( | ) |
Destructor.
Definition at line 82 of file gtimerlist.cpp.
void GNet::TimerList::add | ( | TimerBase & | t, |
ExceptionSink | es | ||
) |
Adds a timer. Called from the Timer constructor.
Definition at line 88 of file gtimerlist.cpp.
|
noexcept |
Resets any matching ExceptionHandler pointers.
Definition at line 107 of file gtimerlist.cpp.
void GNet::TimerList::doTimeouts | ( | ) |
Triggers the timeout callbacks of any expired timers.
Called by the event loop (GNet::EventLoop). Any exception thrown out of an expired timer's callback is caught and delivered back to the ExceptionSink associated with the timer.
Definition at line 221 of file gtimerlist.cpp.
|
static |
Returns true if instance() exists.
Definition at line 175 of file gtimerlist.cpp.
|
static |
Singleton access. Throws an exception if none.
Definition at line 180 of file gtimerlist.cpp.
std::pair< G::TimeInterval, bool > GNet::TimerList::interval | ( | ) | const |
Returns the interval to the first timer expiry.
The second part is an 'infinite' flag that is set if there are no timers running. In pathological cases the interval will be capped at the type's maximum value.
Definition at line 149 of file gtimerlist.cpp.
|
staticnoexcept |
Singleton access. Returns nullptr if none.
Definition at line 170 of file gtimerlist.cpp.
|
noexcept |
Removes a timer from the list.
Called from the Timer destructor.
Definition at line 93 of file gtimerlist.cpp.
std::string GNet::TimerList::report | ( | ) | const |
Returns a line of text reporting the status of the timer list.
Used in debugging and diagnostics.
Definition at line 256 of file gtimerlist.cpp.
void GNet::TimerList::updateOnCancel | ( | TimerBase & | timer | ) |
Called by Timer when a timer is cancelled.
Definition at line 131 of file gtimerlist.cpp.
void GNet::TimerList::updateOnStart | ( | TimerBase & | timer | ) |
Called by Timer when a timer is started.
Definition at line 119 of file gtimerlist.cpp.
|
friend |
Definition at line 158 of file gtimerlist.h.
|
friend |
Definition at line 159 of file gtimerlist.h.