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...
ExceptionHandler * | eh () const noexcept
| Returns the exception handler pointer. More...
ExceptionSource * | esrc () const noexcept
| Returns the exception source pointer. More...
EventLogging * | logging () 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
} ;
GNet::EventState::EventState
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 ;
} ;
GNet::EventState::logging
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
| inline noexcept

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
| inline noexcept

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
| inline noexcept

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
| inline noexcept

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
| inline noexcept

Returns true if eh() is not null.

Definition at line 287 of file geventstate.h.

## ◆ logging() [1/2]

GNet::EventLogging * GNet::EventState::logging | ( |  | ) | const
| inline noexcept

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
| inline noexcept

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:

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/geventstate.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/geventstate.cpp