E-MailRelay

Public Member Functions | Static Public Member Functions | List of all members
GNet::FutureEvent Class Reference

A FutureEvent object can be used to send a one-shot event between threads via the event loop, resulting in a call to the relevant event handler. More...

`#include <gfutureevent.h>`

## Public Member Functions
| FutureEvent (FutureEventHandler &, EventState)
| Constructor. Installs itself in the event loop. More...
| ~FutureEvent ()
| Destructor.
HANDLE | handle () noexcept
| Extracts a handle that can be passed between threads and used in send(). More...
| FutureEvent (const FutureEvent &)=delete
| FutureEvent (FutureEvent &&)=delete
FutureEvent & | operator= (const FutureEvent &)=delete
FutureEvent & | operator= (FutureEvent &&)=delete

## Static Public Member Functions
static bool | send (HANDLE handle, bool close=true) noexcept
| Pokes an event into the main event loop so that the FutureEventHandler callback is called asynchronously. More...
static HANDLE | createHandle ()
| Used by some event loop implementations to create the underlying synchronisation object. More...

## Detailed Description

A FutureEvent object can be used to send a one-shot event between threads via the event loop, resulting in a call to the relevant event handler.

This is used in the implementation of multi-threaded asynchronous task classes such as GNet::Task and GNet::Resolver.

The thread-safe trigger function send() is typically called from a worker thread just before the thread finishes.

Eg:

struct Foo : private FutureEventHandler , private ExceptionHandler
{
Foo() ;
G::Slot::signal<int> m_signal ;
private:
void run( HANDLE ) ;
void onFutureEvent() override ;
FutureEvent m_future_event ;
std::thread m_thread ;
int m_result ;
}
Foo::Foo() :
m_future_event(*this,*this) ,
m_thread(&Foo::run,this,m_future_event.handle())
{
}
void Foo::run( HANDLE h )
{
// this is the worker thread spun off from the ctor
m_result = ... ; // do blocking work
FutureEvent::send( h ) ; // raise 'work complete' event
}
void Foo::onFutureEvent()
{
m_signal.emit( m_result ) ;
}
GNet::FutureEvent::FutureEvent
FutureEvent(FutureEventHandler &, EventState)
Constructor. Installs itself in the event loop.
Definition: gfutureevent_unix.cpp:150
GNet::FutureEvent::handle
HANDLE handle() noexcept
Extracts a handle that can be passed between threads and used in send().
Definition: gfutureevent_unix.cpp:163

The typical implementation uses a socketpair, with the read socket's file descriptor registered with the event loop in the normal way and the socket event handler delegating to the future-event handler.

Definition at line 81 of file gfutureevent.h.

## Constructor & Destructor Documentation

## ◆ FutureEvent()

GNet::FutureEvent::FutureEvent | ( | FutureEventHandler & | handler,
|  | EventState | es
| ) |  |

Constructor. Installs itself in the event loop.

Definition at line 150 of file gfutureevent_unix.cpp.

## Member Function Documentation

## ◆ createHandle()

HANDLE GNet::FutureEvent::createHandle | ( |  | ) |
| static

Used by some event loop implementations to create the underlying synchronisation object.

Definition at line 166 of file gfutureevent_win32.cpp.

## ◆ handle()

HANDLE GNet::FutureEvent::handle | ( |  | ) |
| noexcept

Extracts a handle that can be passed between threads and used in send().

This should be called once, typically as the worker thread is created.

Definition at line 163 of file gfutureevent_unix.cpp.

## ◆ send()

bool GNet::FutureEvent::send | ( | HANDLE | handle,
|  | bool | close = `true`
| ) |  |
| static noexcept

Pokes an event into the main event loop so that the FutureEventHandler callback is called asynchronously.

Should be called exactly once with 'close' true if handle() has been called, typically just before the worker thread finishes.

This is safe even if the FutureEvent object has been deleted. Returns true on success.

Definition at line 158 of file gfutureevent_unix.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gfutureevent.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gfutureevent_unix.cpp
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gfutureevent_win32.cpp