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 &, 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

## 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 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.

## Constructor & Destructor Documentation

## ◆ TimerList()

GNet::TimerList::TimerList | ( |  | ) |

Default constructor.

Definition at line 76 of file gtimerlist.cpp.

## ◆ ~TimerList()

GNet::TimerList::~TimerList | ( |  | ) |

Destructor.

Definition at line 82 of file gtimerlist.cpp.

## Member Function Documentation

## ◆ add()

void GNet::TimerList::add | ( | TimerBase & | t,
|  | ExceptionSink | es
| ) |  |

Adds a timer. Called from the Timer constructor.

Definition at line 88 of file gtimerlist.cpp.

## ◆ disarm()

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

Resets any matching ExceptionHandler pointers.

Definition at line 107 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 ExceptionSink associated with the timer.

Definition at line 221 of file gtimerlist.cpp.

## ◆ exists()

bool GNet::TimerList::exists | ( |  | ) |
| static

Returns true if instance() exists.

Definition at line 175 of file gtimerlist.cpp.

## ◆ instance()

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

Singleton access. Throws an exception if none.

Definition at line 180 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 | ( |  | ) |
| static noexcept

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 93 of file gtimerlist.cpp.

## ◆ report()

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.

## ◆ updateOnCancel()

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

Called by Timer when a timer is cancelled.

Definition at line 131 of file gtimerlist.cpp.

## ◆ updateOnStart()

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

Called by Timer when a timer is started.

Definition at line 119 of file gtimerlist.cpp.

## Friends And Related Function Documentation

## ◆ GNet::TimerListTest

friend class GNet::TimerListTest
| friend

Definition at line 158 of file gtimerlist.h.

## ◆ Lock

friend struct Lock
| friend

Definition at line 159 of file gtimerlist.h.

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

- /usr/src/slapt-src-x86_64/network/emailrelay/emailrelay-2.3/src/gnet/gtimerlist.h
- /usr/src/slapt-src-x86_64/network/emailrelay/emailrelay-2.3/src/gnet/gtimerlist.cpp