E-MailRelay
Classes | Public Member Functions | Static Public Member Functions | Friends | List of all members
GNet::TimerList Class Reference

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 &, EventState)
 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...
 
void disarm (ExceptionHandler *) noexcept
 Resets any matching ExceptionHandler pointers. More...
 
 TimerList (const TimerList &)=delete
 
 TimerList (TimerList &&)=delete
 
TimerListoperator= (const TimerList &)=delete
 
TimerListoperator= (TimerList &&)=delete
 

Static Public Member Functions

static bool exists ()
 Returns true if instance() exists. More...
 
static TimerListptr () noexcept
 Singleton access. Returns nullptr if none. More...
 
static TimerListinstance ()
 Singleton access. Throws an exception if none. More...
 

Friends

class GNet::TimerListTest
 
struct Lock
 

Detailed Description

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 this is zero, or after their event-waiting times-out, they should 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 EventLoop.

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 70 of file gtimerlist.h.

Constructor & Destructor Documentation

◆ TimerList()

GNet::TimerList::TimerList ( )

Default constructor.

Definition at line 75 of file gtimerlist.cpp.

◆ ~TimerList()

GNet::TimerList::~TimerList ( )

Destructor.

Definition at line 81 of file gtimerlist.cpp.

Member Function Documentation

◆ add()

void GNet::TimerList::add ( TimerBase t,
EventState  es 
)

Adds a timer. Called from the Timer constructor.

Definition at line 87 of file gtimerlist.cpp.

◆ disarm()

void GNet::TimerList::disarm ( ExceptionHandler eh)
noexcept

Resets any matching ExceptionHandler pointers.

Definition at line 106 of file gtimerlist.cpp.

◆ doTimeouts()

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 EventState associated with the timer.

Definition at line 227 of file gtimerlist.cpp.

◆ exists()

bool GNet::TimerList::exists ( )
static

Returns true if instance() exists.

Definition at line 176 of file gtimerlist.cpp.

◆ instance()

GNet::TimerList & GNet::TimerList::instance ( )
static

Singleton access. Throws an exception if none.

Definition at line 182 of file gtimerlist.cpp.

◆ interval()

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.

◆ ptr()

GNet::TimerList * GNet::TimerList::ptr ( )
staticnoexcept

Singleton access. Returns nullptr if none.

Definition at line 170 of file gtimerlist.cpp.

◆ remove()

void GNet::TimerList::remove ( TimerBase timer)
noexcept

Removes a timer from the list.

Called from the Timer destructor.

Definition at line 92 of file gtimerlist.cpp.

◆ updateOnCancel()

void GNet::TimerList::updateOnCancel ( TimerBase timer)

Called by Timer when a timer is cancelled.

Definition at line 130 of file gtimerlist.cpp.

◆ updateOnStart()

void GNet::TimerList::updateOnStart ( TimerBase timer)

Called by Timer when a timer is started.

Definition at line 118 of file gtimerlist.cpp.

Friends And Related Function Documentation

◆ GNet::TimerListTest

friend class GNet::TimerListTest
friend

Definition at line 146 of file gtimerlist.h.

◆ Lock

friend struct Lock
friend

Definition at line 147 of file gtimerlist.h.


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