E-MailRelay
gfutureevent.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 "gexception.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 /// An object that hooks into the event loop and calls back to the client
37 /// code. The trigger function send() is typically called from a
38 /// "future/promise" worker thread just before it finishes.
39 ///
40 /// Eg:
41 /// \code
42 /// struct Foo : private FutureEventHandler , private ExceptionHandler
43 /// {
44 /// Foo() ;
45 /// void onFutureEvent( unsigned int result ) ;
46 /// void run( FutureEvent::handle_type ) ;
47 /// FutureEvent m_future_event ;
48 /// std::thread m_thread ;
49 /// }
50 /// Foo::Foo() :
51 /// m_future_event(*this,*this) ,
52 /// m_thread(&Foo::run,this,m_future_event.handle())
53 /// {
54 /// }
55 /// void Foo::run( FutureEvent::handle_type h )
56 /// {
57 /// ... // do blocking work
58 /// FutureEvent::send( h ) ;
59 /// }
60 /// \endcode
61 ///
63 {
64 public:
65  G_EXCEPTION( Error , "FutureEvent error" ) ;
66  typedef HANDLE handle_type ;
67 
69  ///< Constructor. Installs itself in the event loop.
70 
71  ~FutureEvent() ;
72  ///< Destructor.
73 
74  handle_type handle() ;
75  ///< Returns a handle that can be passed between threads
76  ///< and used in send(). This should be called once.
77 
78  static bool send( handle_type handle ) g__noexcept ;
79  ///< Pokes an event into the main event loop so that the
80  ///< FutureEventHandler callback is called asynchronously.
81  ///<
82  ///< Should be called exactly once if handle() has been
83  ///< called.
84  ///<
85  ///< This is safe even if the FutureEvent object has been
86  ///< deleted. Returns true on success.
87 
88 private:
89  FutureEvent( const FutureEvent & ) ;
90  void operator=( const FutureEvent & ) ;
91 
92 private:
93  friend class FutureEventImp ;
94  unique_ptr<FutureEventImp> m_imp ;
95 } ;
96 
97 /// \class GNet::FutureEventHandler
98 /// A callback interface for GNet::FutureEvent.
99 ///
101 {
102 public:
103  virtual void onFutureEvent() = 0 ;
104  ///< Callback function that delivers the future event.
105 
106 protected:
107  virtual ~FutureEventHandler() ;
108  ///< Destructor.
109 
110 private:
111  void operator=( const FutureEventHandler & ) ;
112 } ;
113 
114 #endif
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:100
Network classes.
Definition: gaddress.h:29
An object that hooks into the event loop and calls back to the client code.
Definition: gfutureevent.h:62
~FutureEvent()
Destructor.
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
FutureEvent(FutureEventHandler &, ExceptionHandler &)
Constructor. Installs itself in the event loop.
virtual ~FutureEventHandler()
Destructor.
A pimple-pattern implementation class used by GNet::FutureEvent.
static bool send(handle_type handle) g__noexcept
Pokes an event into the main event loop so that the FutureEventHandler callback is called asynchronou...
virtual void onFutureEvent()=0
Callback function that delivers the future event.
handle_type handle()
Returns a handle that can be passed between threads and used in send().