E-MailRelay

gfutureevent.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gfutureevent.h
19///
20
21#ifndef G_NET_FUTURE_EVENT_H
22#define G_NET_FUTURE_EVENT_H
23
24#include "gdef.h"
25#include "gexceptionsink.h"
26#include "geventhandler.h"
27
28 namespace GNet
29{
30 class FutureEvent ;
31 class FutureEventHandler ;
32 class FutureEventImp ;
33}
34
35//| \class GNet::FutureEvent
36/// A FutureEvent object can be used to send a one-shot event via the
37/// event loop to the relevant event handler. Used in the implementation
38/// of 'future' classes.
39///
40/// The thread-safe trigger function send() is typically called from
41/// a 'future' worker thread just before it finishes.
42///
43/// Eg:
44/// \code
45/// struct Foo : private FutureEventHandler , private ExceptionHandler
46/// {
47/// Foo() ;
48/// void onFutureEvent() ;
49/// void run( FutureEvent::handle_type ) ;
50/// FutureEvent m_future_event ;
51/// std::thread m_thread ;
52/// int m_result ;
53/// }
54/// Foo::Foo() :
55/// m_future_event(*this,*this) ,
56/// m_thread(&Foo::run,this,m_future_event.handle())
57/// {
58/// }
59/// void Foo::run( FutureEvent::handle_type h )
60/// {
61/// m_result = ... ; // do blocking work in worker thread
62/// FutureEvent::send( h ) ; // raise 'work complete' event
63/// }
64/// \endcode
65///
66/// The typical implementation uses a socketpair, with the read socket's
67/// file descriptor registered with the event loop in the normal way
68/// and the socket event handler delegating to the future-event
69/// handler.
70///
71 class GNet::FutureEvent
72{
73 public:
74 G_EXCEPTION( Error , "FutureEvent error" ) ;
75 using handle_type = HANDLE ;
76
77 FutureEvent( FutureEventHandler & , ExceptionSink ) ;
78 ///< Constructor. Installs itself in the event loop.
79
80 ~FutureEvent() ;
81 ///< Destructor.
82
83 handle_type handle() noexcept ;
84 ///< Extracts a handle that can be passed between threads
85 ///< and used in send(). This should be called once,
86 ///< typically as the worker thread is created.
87
88 static bool send( handle_type handle , bool close = true ) noexcept ;
89 ///< Pokes an event into the main event loop so that the
90 ///< FutureEventHandler callback is called asynchronously.
91 ///<
92 ///< Should be called exactly once with 'close' true
93 ///< if handle() has been called, typically just before
94 ///< the worker thread finishes.
95 ///<
96 ///< This is safe even if the FutureEvent object has been
97 ///< deleted. Returns true on success.
98
99public:
100 FutureEvent( const FutureEvent & ) = delete ;
101 FutureEvent( FutureEvent && ) = delete ;
102 void operator=( const FutureEvent & ) = delete ;
103 void operator=( FutureEvent && ) = delete ;
104
105private:
106 std::unique_ptr<FutureEventImp> m_imp ;
107} ;
108
109//| \class GNet::FutureEventHandler
110/// A callback interface for GNet::FutureEvent.
111///
112 class GNet::FutureEventHandler
113{
114 public:
115 virtual ~FutureEventHandler() = default ;
116 ///< Destructor.
117
118 virtual void onFutureEvent() = 0 ;
119 ///< Callback function that delivers the future event.
120} ;
121
122#endif
GNet::ExceptionSink
A tuple containing an ExceptionHandler interface pointer and a bound 'exception source' pointer.
Definition: gexceptionsink.h:100
GNet::FutureEventHandler
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:113
GNet::FutureEventHandler::onFutureEvent
virtual void onFutureEvent()=0
Callback function that delivers the future event.
GNet::FutureEventHandler::~FutureEventHandler
virtual ~FutureEventHandler()=default
Destructor.
GNet::FutureEventImp
A pimple-pattern implementation class used by GNet::FutureEvent.
Definition: gfutureevent_unix.cpp:34
GNet::FutureEvent
A FutureEvent object can be used to send a one-shot event via the event loop to the relevant event ha...
Definition: gfutureevent.h:72
GNet::FutureEvent::FutureEvent
FutureEvent(FutureEventHandler &, ExceptionSink)
Constructor. Installs itself in the event loop.
Definition: gfutureevent_unix.cpp:149
GNet::FutureEvent::handle
handle_type handle() noexcept
Extracts a handle that can be passed between threads and used in send().
Definition: gfutureevent_unix.cpp:162
GNet::FutureEvent::send
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 asynchronou...
Definition: gfutureevent_unix.cpp:157
GNet::FutureEvent::~FutureEvent
~FutureEvent()
Destructor.
geventhandler.h
gexceptionsink.h
GNet
Network classes.
Definition: gdef.h:1115