E-MailRelay

Classes | Public Member Functions | List of all members
GNet::EventHandlerList Class Reference

A class that maps from a file descriptor to an event handler and exception handler, used in the implemention of classes derived from GNet::EventLoop. More...

`#include <geventhandlerlist.h>`

## Classes
struct | Iterator
| An iterator for GNet::EventHandlerList. More...
struct | Lock
| A RAII class to lock and unlock GNet::EventHandlerList. More...
struct | Value
| A tuple for GNet::EventHandlerList. More...

## Public Member Functions
| EventHandlerList (const std::string &type)
| Constructor. More...
void | add (Descriptor fd, EventHandler *handler, ExceptionSink)
| Adds a file-descriptor/handler tuple to the list. More...
void | remove (Descriptor fd) noexcept
| Removes a file-descriptor from the list. More...
Iterator | find (Descriptor fd) const
| Finds an entry in the list. More...
bool | contains (Descriptor fd) const noexcept
| Returns true if the list, taking account of any pending changes, contains the given descriptor. More...
void | lock ()
| To be called at the start of an begin()/end() iteration if the list might change during the iteration. More...
bool | unlock ()
| Called at the end of a begin()/end() iteration to match a call to lock(). More...
Iterator | begin () const noexcept
| Returns a forward iterator. More...
Iterator | end () const noexcept
| Returns an end iterator. More...
void | disarm (ExceptionHandler *) noexcept
| Resets any matching ExceptionHandler pointers, so exceptions thrown out of the relevant file descriptors' event handlers are rethrown by this class rather than being delivered to the exception handler interface. More...
void | getHandles (std::vector< HANDLE > &) const
| Adds unique, non-zero Descriptor handles to the given sorted list, including any add()ed while lock()ed. More...
std::size_t | size () const noexcept
| Returns the size of the list, ignoring any changes while lock()ed. More...
| EventHandlerList (const EventHandlerList &)=delete
| EventHandlerList (EventHandlerList &&)=delete
void | operator= (const EventHandlerList &)=delete
void | operator= (EventHandlerList &&)=delete

## Detailed Description

A class that maps from a file descriptor to an event handler and exception handler, used in the implemention of classes derived from GNet::EventLoop.

If an event handler is removed from the list while the list is being iterated over then the relevant pointer is reset without affecting the iteration. The unlock() method does garbage collection once the iteration is complete.

If an event handler is added to the list while the list is being iterated over then it is added to a pending-list. The pending list is added to the main list by unlock() once the iteration is complete.

Each event handler has an associated exception handler, typically a more long-lived object that has the event handler as a sub-object. If the event hander throws an exception then the event handler 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 list's disarm() mechanism. This is the same behaviour as in the TimerList.

Exception handlers are combined with an additional 'source' pointer in an ExceptionSink tuple. The exception source pointer can be used to provide additional information to the exception handler, typically as a pointer to the event handler object. (The EventHandler class is not used as the exception source type because timers also refer to exception sources and because of possible multiple inheritance of the EventHandler base.)

Note that the Descriptor class is actually in two parts for Windows: a socket handle (file descriptor) and an event-object handle. The event handler list is keyed by the full Descriptor object rather than just the socket handle and this allows it to contain event-handling objects that are not sockets. See GNet::FutureEvent.

Definition at line 75 of file geventhandlerlist.h.

## Constructor & Destructor Documentation

## ◆ EventHandlerList()

GNet::EventHandlerList::EventHandlerList | ( | const std::string & | type | ) |
| explicit

Constructor.

The type parameter (eg. "read") is used only in debugging messages.

Definition at line 44 of file geventhandlerlist.cpp.

## Member Function Documentation

## ◆ add()

void GNet::EventHandlerList::add | ( | Descriptor | fd,
|  | EventHandler * | handler,
|  | ExceptionSink | es
| ) |  |

Adds a file-descriptor/handler tuple to the list.

Definition at line 51 of file geventhandlerlist.cpp.

## ◆ begin()

GNet::EventHandlerList::Iterator GNet::EventHandlerList::begin | ( |  | ) | const
| inline noexcept

Returns a forward iterator.

If the list is lock()ed then the iterator will skip over descriptors that have been remove()d or add()ed while locked.

Definition at line 210 of file geventhandlerlist.h.

## ◆ contains()

bool GNet::EventHandlerList::contains | ( | Descriptor | fd | ) | const
| noexcept

Returns true if the list, taking account of any pending changes, contains the given descriptor.

Definition at line 132 of file geventhandlerlist.cpp.

## ◆ disarm()

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

Resets any matching ExceptionHandler pointers, so exceptions thrown out of the relevant file descriptors' event handlers are rethrown by this class rather than being delivered to the exception handler interface.

Definition at line 109 of file geventhandlerlist.cpp.

## ◆ end()

GNet::EventHandlerList::Iterator GNet::EventHandlerList::end | ( |  | ) | const
| inline noexcept

Returns an end iterator.

Definition at line 216 of file geventhandlerlist.h.

## ◆ find()

GNet::EventHandlerList::Iterator GNet::EventHandlerList::find | ( | Descriptor | fd | ) | const

Finds an entry in the list.

Returns end() if not found. This ignores any pending changes, ie. descriptors add()ed or remove()d while lock()ed.

Definition at line 124 of file geventhandlerlist.cpp.

## ◆ getHandles()

void GNet::EventHandlerList::getHandles | ( | std::vector< HANDLE > & | out | ) | const

Adds unique, non-zero Descriptor handles to the given sorted list, including any add()ed while lock()ed.

Definition at line 148 of file geventhandlerlist.cpp.

## ◆ lock()

void GNet::EventHandlerList::lock | ( |  | ) |

To be called at the start of an begin()/end() iteration if the list might change during the iteration.

Must be paired with unlock().

Definition at line 168 of file geventhandlerlist.cpp.

## ◆ remove()

void GNet::EventHandlerList::remove | ( | Descriptor | fd | ) |
| noexcept

Removes a file-descriptor from the list.

Does nothing if the file-descriptor is not in the list.

Definition at line 71 of file geventhandlerlist.cpp.

## ◆ size()

std::size_t GNet::EventHandlerList::size | ( |  | ) | const
| noexcept

Returns the size of the list, ignoring any changes while lock()ed.

Definition at line 143 of file geventhandlerlist.cpp.

## ◆ unlock()

bool GNet::EventHandlerList::unlock | ( |  | ) |

Called at the end of a begin()/end() iteration to match a call to lock().

Does garbage collection. Returns true if anything might have changed.

Definition at line 173 of file geventhandlerlist.cpp.

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

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