E-MailRelay
geventloop.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 geventloop.h
19 ///
20 
21 #ifndef G_NET_EVENT_LOOP__H
22 #define G_NET_EVENT_LOOP__H
23 
24 #include "gdef.h"
25 #include "geventhandler.h"
26 #include "gexceptionhandler.h"
27 #include "gexception.h"
28 #include "gdescriptor.h"
29 #include "gsignalsafe.h"
30 #include <list>
31 #include <string>
32 
33 namespace GNet
34 {
35  class EventLoop ;
36 }
37 
38 /// \class GNet::EventLoop
39 /// An abstract base class for a singleton that keeps track of open sockets
40 /// and their associated handlers. Derived classes are used to implement
41 /// different event loops, such as select() or WaitForMultipleObjects().
42 ///
43 /// In practice sockets should be added and removed from the class by
44 /// calling GNet::Socket::addReadHandler() and friends rather than by calling
45 /// EventLoop::addRead() etc. so that the event handle is passed correctly
46 /// when running on windows.
47 ///
48 /// The class has a static member for finding an instance, but instances
49 /// are not created automatically.
50 ///
51 /// As a convenience the event loop is also an ExceptionHandler that does
52 /// a rethrow.
53 ///
55 {
56 public:
57  G_EXCEPTION( Error , "failed to initialise the event loop" ) ;
58  G_EXCEPTION( NoInstance , "no event loop instance" ) ;
59 
60 protected:
61  EventLoop() ;
62  ///< Constructor.
63 
64  struct Running /// RAII class that sets a boolean, for implementations of run()/running().
65  {
66  Running( bool & bref ) : m_bref(bref) { m_bref = true ; }
67  ~Running() { m_bref = false ; }
68  bool & m_bref ;
69  } ;
70 
71 public:
72  static EventLoop * create() ;
73  ///< A factory method which creates an instance of a derived
74  ///< class on the heap. Throws on error.
75 
76  static EventLoop & instance() ;
77  ///< Returns a reference to an instance of the class,
78  ///< if any. Throws if none. Does not do any instantiation
79  ///< itself.
80 
81  static bool exists() ;
82  ///< Returns true if an instance exists.
83 
84  static void stop( const G::SignalSafe & ) ;
85  ///< Calls quit() on instance().
86 
87  virtual ~EventLoop() ;
88  ///< Destructor.
89 
90  virtual std::string run() = 0 ;
91  ///< Runs the main event loop. Returns a quit() reason,
92  ///< if any.
93 
94  virtual bool running() const = 0 ;
95  ///< Returns true if called from within run().
96 
97  virtual void quit( std::string reason ) = 0 ;
98  ///< Causes run() to return (once the call stack has
99  ///< unwound). If there are multiple quit()s before
100  ///< run() returns then the latest reason is used.
101 
102  virtual void quit( const G::SignalSafe & ) = 0 ;
103  ///< A signal-safe overload to quit() the event loop.
104 
105  virtual void addRead( Descriptor fd , EventHandler & , ExceptionHandler & ) = 0 ;
106  ///< Adds the given event source descriptor and associated
107  ///< handler to the read list.
108  ///< See also Socket::addReadHandler().
109 
110  virtual void addWrite( Descriptor fd , EventHandler & , ExceptionHandler & ) = 0 ;
111  ///< Adds the given event source descriptor and associated
112  ///< handler to the write list.
113  ///< See also Socket::addWriteHandler().
114 
115  virtual void addOther( Descriptor fd , EventHandler & , ExceptionHandler & ) = 0 ;
116  ///< Adds the given event source descriptor and associated
117  ///< handler to the exception list.
118  ///< See also Socket::addOtherHandler().
119 
120  virtual void dropRead( Descriptor fd ) = 0 ;
121  ///< Removes the given event source descriptor from the
122  ///< list of read sources.
123  ///< See also Socket::dropReadHandler().
124 
125  virtual void dropWrite( Descriptor fd ) = 0 ;
126  ///< Removes the given event source descriptor from the
127  ///< list of write sources.
128  ///< See also Socket::dropWriteHandler().
129 
130  virtual void dropOther( Descriptor fd ) = 0 ;
131  ///< Removes the given event source descriptor from the
132  ///< list of exception sources.
133  ///< See also Socket::dropOtherHandler().
134 
135  virtual void setTimeout( G::EpochTime t ) = 0 ;
136  ///< Used by GNet::TimerList. Sets the absolute time at which
137  ///< TimerList::doTimeouts() is to be called. A zero time
138  ///< is used if there are no active timers.
139 
140  virtual std::string report() const = 0 ;
141  ///< Returns a line of text reporting the status of the event loop.
142  ///< Used in debugging and diagnostics.
143 
144  virtual void disarm( ExceptionHandler * ) = 0 ;
145  ///< Used to prevent the given interface from being used,
146  ///< typically called from the ExceptionHandler
147  ///< destructor.
148 
149  virtual void onException( std::exception & ) override ;
150  ///< Override from ExceptionHandler that just rethrows
151  ///< the current exception.
152 
153 private:
154  static EventLoop * m_this ;
155 } ;
156 
157 #endif
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
virtual void setTimeout(G::EpochTime t)=0
Used by GNet::TimerList.
static void stop(const G::SignalSafe &)
Calls quit() on instance().
Definition: geventloop.cpp:55
Network classes.
Definition: gaddress.h:29
An empty structure that is used to indicate a signal-safe, reentrant implementation.
Definition: gsignalsafe.h:36
An abstract base class for a singleton that keeps track of open sockets and their associated handlers...
Definition: geventloop.h:54
virtual void onException(std::exception &) override
Override from ExceptionHandler that just rethrows the current exception.
Definition: geventloop.cpp:61
virtual void dropRead(Descriptor fd)=0
Removes the given event source descriptor from the list of read sources.
A class that encapsulates a network socket file descriptor and an associated windows event handle...
Definition: gdescriptor.h:36
virtual void addRead(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the read list.
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
virtual void addWrite(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the write list.
static EventLoop * create()
A factory method which creates an instance of a derived class on the heap.
virtual void disarm(ExceptionHandler *)=0
Used to prevent the given interface from being used, typically called from the ExceptionHandler destr...
virtual bool running() const =0
Returns true if called from within run().
virtual std::string run()=0
Runs the main event loop.
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:47
EventLoop()
Constructor.
Definition: geventloop.cpp:28
RAII class that sets a boolean, for implementations of run()/running().
Definition: geventloop.h:64
virtual std::string report() const =0
Returns a line of text reporting the status of the event loop.
static bool exists()
Returns true if an instance exists.
Definition: geventloop.cpp:50
virtual ~EventLoop()
Destructor.
Definition: geventloop.cpp:36
virtual void dropOther(Descriptor fd)=0
Removes the given event source descriptor from the list of exception sources.
virtual void dropWrite(Descriptor fd)=0
Removes the given event source descriptor from the list of write sources.
virtual void addOther(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the exception list.
static EventLoop & instance()
Returns a reference to an instance of the class, if any.
Definition: geventloop.cpp:42
virtual void quit(std::string reason)=0
Causes run() to return (once the call stack has unwound).