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

A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and optional EventLogging pointer. More...

#include <geventstate.h>

Classes

struct  Private
 Overload discriminator for GNet::EventState. More...
 

Public Member Functions

 EventState (Private, ExceptionHandler *eh, ExceptionSource *source) noexcept
 Constructor used by event loops etc. More...
 
EventState esrc (Private, ExceptionSource *) const noexcept
 Returns a copy of this object with the ExceptionSource pointer set. More...
 
EventState eh (ExceptionHandler *, ExceptionSource *=nullptr) const noexcept
 Returns a copy of this object with the ExceptionHandler and ExceptionSource set. More...
 
EventState eh (ExceptionHandler &, ExceptionSource *=nullptr) const noexcept
 Returns a copy of this object with the ExceptionHandler and ExceptionSource set. More...
 
EventState logging (EventLogging *) const noexcept
 Returns a copy of this object with the ExceptionLogging pointer set to the given value. More...
 
EventStateUnbound unbound () const noexcept
 Returns a copy of this object as type EventStateUnbound with a null ExceptionSource. More...
 
ExceptionHandlereh () const noexcept
 Returns the exception handler pointer. More...
 
ExceptionSourceesrc () const noexcept
 Returns the exception source pointer. More...
 
EventLogginglogging () const noexcept
 Returns the event logging pointer. More...
 
bool hasExceptionHandler () const noexcept
 Returns true if eh() is not null. More...
 
void doOnException (std::exception &e, bool done)
 Calls the exception handler's onException() method. More...
 
void disarm () noexcept
 Resets the exception handler. More...
 
void eh (std::nullptr_t, ExceptionSource *) const =delete
 
void logging (std::nullptr_t) const =delete
 

Static Public Member Functions

static EventState create ()
 A factory function for an exception handler that rethrows. More...
 
static EventState create (std::nothrow_t)
 A factory function for an exception handler that logs the exception as an error but does not re-throw. More...
 

Detailed Description

A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and optional EventLogging pointer.

Instances are used in the event loop and timer list and they are also copied throughout the containment hierarchy of network and timer objects: the parent object's EventState object is passed to the constructor of all the child objects that it contains. When an object regiters with the event loop it passes its EventState object for the event loop to use when it calls back with an event. If an object can outlast its container (eg. GNet::TaskImp) then it must create() a fresh EventState object, independent of its container.

An ExceptionHandler implementation normally just rethrows the exception to terminate the event loop, but sometimes the exception can be handled less drastically, perhaps by deleting the object identified as the exception source.

For example, Server objects create and contain ServerPeer objects:

class ServerPeer : public ExceptionSource { ... } ;
class Server : private ExceptionHandler
{
void init() { m_peer = newServerPeer(...) ; }
void onException( ExceptionSource * source ... ) override
{
assert( source == m_peer ) ;
delete source ;
}
ServerPeer * m_peer ;
} ;

The EventStateUnbound class is used as a device to force factory methods to plumb-in an ExceptionSource pointer into the newly-created object as soon as its address is available, before the EventState propagates into base classes and sub-objects.

class FooServer
{
public:
void accept()
{
std::make_unique<FooServerPeer>( m_es.unbound() , ... ) ;
}
EventState m_es ;
} ;
class FooServerPeer : public FooBase , public ExceptionSource
{
public:
FooServerPeer( EventStateUnbound esu , ... ) :
FooBase(esbind(esu,this),...) ,
m_es(esbind(esu,this)) ,
m_sub_object(m_es)
{
}
EventState m_es ; // first
FooItem m_sub_object ; // eg. timer
} ;
EventState(Private, ExceptionHandler *eh, ExceptionSource *source) noexcept
Constructor used by event loops etc.
Definition: geventstate.cpp:44

To automatically set a G::LogOutput logging context during event processing certain key classes in the containment tree should override GNet::EventLogging::eventLoggingString() and set the logging interface pointer in their EventState:

struct Foo : EventLogging , FooBase
{
Foo( EventState es , ... ) :
EventLogging(es.logging()) ,
FooBase(es.logging(this),...) ,
m_es(es.logging(this)) ,
m_event_logging_string("foo: ")
{
}
std::string_view eventLoggingString() const override
{
return m_event_logging_string ;
}
EventState m_es ;
std::string m_event_logging_string ;
} ;
EventLogging * logging() const noexcept
Returns the event logging pointer.
Definition: geventstate.h:281

Definition at line 130 of file geventstate.h.

Constructor & Destructor Documentation

◆ EventState()

GNet::EventState::EventState ( Private  ,
ExceptionHandler eh,
ExceptionSource source 
)
noexcept

Constructor used by event loops etc.

The ExceptionHandler pointer must remain valid as the EventState is copied around.

Definition at line 44 of file geventstate.cpp.

Member Function Documentation

◆ create() [1/2]

GNet::EventState GNet::EventState::create ( )
static

A factory function for an exception handler that rethrows.

Definition at line 58 of file geventstate.cpp.

◆ create() [2/2]

GNet::EventState GNet::EventState::create ( std::nothrow_t  )
static

A factory function for an exception handler that logs the exception as an error but does not re-throw.

This can be a convenient alternative to a try/catch block for code that might throw but should not terminate a long-running server process.

Definition at line 50 of file geventstate.cpp.

◆ disarm()

void GNet::EventState::disarm ( )
noexcept

Resets the exception handler.

Postcondition: !hasExceptionHandler()

Definition at line 85 of file geventstate.cpp.

◆ doOnException()

void GNet::EventState::doOnException ( std::exception &  e,
bool  done 
)

Calls the exception handler's onException() method.

Used by EventEmitter and TimerList when handling an exception thrown from an event handler. Precondition: hasExceptionHandler()

Definition at line 79 of file geventstate.cpp.

◆ eh() [1/3]

GNet::ExceptionHandler * GNet::EventState::eh ( ) const
inlinenoexcept

Returns the exception handler pointer.

Definition at line 263 of file geventstate.h.

◆ eh() [2/3]

GNet::EventState GNet::EventState::eh ( ExceptionHandler eh,
ExceptionSource esrc = nullptr 
) const
inlinenoexcept

Returns a copy of this object with the ExceptionHandler and ExceptionSource set.

Definition at line 254 of file geventstate.h.

◆ eh() [3/3]

GNet::EventState GNet::EventState::eh ( ExceptionHandler eh,
ExceptionSource esrc = nullptr 
) const
inlinenoexcept

Returns a copy of this object with the ExceptionHandler and ExceptionSource set.

Definition at line 245 of file geventstate.h.

◆ esrc() [1/2]

GNet::ExceptionSource * GNet::EventState::esrc ( ) const
inlinenoexcept

Returns the exception source pointer.

Definition at line 269 of file geventstate.h.

◆ esrc() [2/2]

GNet::EventState GNet::EventState::esrc ( Private  ,
ExceptionSource esrc 
) const
noexcept

Returns a copy of this object with the ExceptionSource pointer set.

Used by EventStateUnbound.

Definition at line 72 of file geventstate.cpp.

◆ hasExceptionHandler()

bool GNet::EventState::hasExceptionHandler ( ) const
inlinenoexcept

Returns true if eh() is not null.

Definition at line 287 of file geventstate.h.

◆ logging() [1/2]

GNet::EventLogging * GNet::EventState::logging ( ) const
inlinenoexcept

Returns the event logging pointer.

Definition at line 281 of file geventstate.h.

◆ logging() [2/2]

GNet::EventState GNet::EventState::logging ( EventLogging logging) const
noexcept

Returns a copy of this object with the ExceptionLogging pointer set to the given value.

Definition at line 63 of file geventstate.cpp.

◆ unbound()

GNet::EventStateUnbound GNet::EventState::unbound ( ) const
inlinenoexcept

Returns a copy of this object as type EventStateUnbound with a null ExceptionSource.

Definition at line 275 of file geventstate.h.


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