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
inlinenoexcept

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
inlinenoexcept

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: