E-MailRelay
Public Types | 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 via the event loop to the relevant event handler. More...

#include <gfutureevent.h>

Public Types

using handle_type = HANDLE
 

Public Member Functions

 FutureEvent (FutureEventHandler &, ExceptionSink)
 Constructor. Installs itself in the event loop. More...
 
 ~FutureEvent ()
 Destructor.
 
handle_type handle () noexcept
 Extracts a handle that can be passed between threads and used in send(). More...
 
 FutureEvent (const FutureEvent &)=delete
 
 FutureEvent (FutureEvent &&)=delete
 
void operator= (const FutureEvent &)=delete
 
void operator= (FutureEvent &&)=delete
 

Static Public Member Functions

static bool send (handle_type handle, bool close=true) noexcept
 Pokes an event into the main event loop so that the FutureEventHandler callback is called asynchronously. More...
 

Detailed Description

A FutureEvent object can be used to send a one-shot event via the event loop to the relevant event handler.

Used in the implementation of 'future' classes.

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

Eg:

struct Foo : private FutureEventHandler , private ExceptionHandler
{
Foo() ;
void onFutureEvent() ;
void run( FutureEvent::handle_type ) ;
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( FutureEvent::handle_type h )
{
m_result = ... ; // do blocking work in worker thread
FutureEvent::send( h ) ; // raise 'work complete' event
}
FutureEvent(FutureEventHandler &, ExceptionSink)
Constructor. Installs itself in the event loop.
handle_type handle() noexcept
Extracts a handle that can be passed between threads and used in send().

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 71 of file gfutureevent.h.

Member Typedef Documentation

◆ handle_type

using GNet::FutureEvent::handle_type = HANDLE

Definition at line 75 of file gfutureevent.h.

Constructor & Destructor Documentation

◆ FutureEvent()

GNet::FutureEvent::FutureEvent ( FutureEventHandler handler,
ExceptionSink  es 
)

Constructor. Installs itself in the event loop.

Definition at line 149 of file gfutureevent_unix.cpp.

Member Function Documentation

◆ handle()

GNet::FutureEvent::handle_type 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 162 of file gfutureevent_unix.cpp.

◆ send()

bool GNet::FutureEvent::send ( handle_type  handle,
bool  close = true 
)
staticnoexcept

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 157 of file gfutureevent_unix.cpp.


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