E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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 ///
54 class GNet::EventLoop : public ExceptionHandler
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
G::EpochTime
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
GNet::EventLoop::setTimeout
virtual void setTimeout(G::EpochTime t)=0
Used by GNet::TimerList.
GNet::EventLoop::stop
static void stop(const G::SignalSafe &)
Calls quit() on instance().
Definition: geventloop.cpp:55
GNet
Network classes.
Definition: gaddress.h:29
G::SignalSafe
An empty structure that is used to indicate a signal-safe, reentrant implementation.
Definition: gsignalsafe.h:36
GNet::EventLoop
An abstract base class for a singleton that keeps track of open sockets and their associated handlers...
Definition: geventloop.h:54
GNet::EventLoop::onException
virtual void onException(std::exception &) override
Override from ExceptionHandler that just rethrows the current exception.
Definition: geventloop.cpp:61
gsignalsafe.h
GNet::EventLoop::dropRead
virtual void dropRead(Descriptor fd)=0
Removes the given event source descriptor from the list of read sources.
GNet::Descriptor
A class that encapsulates a network socket file descriptor and an associated windows event handle...
Definition: gdescriptor.h:36
GNet::EventLoop::addRead
virtual void addRead(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the read list.
GNet::ExceptionHandler
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
Definition: gexceptionhandler.h:44
GNet::EventLoop::addWrite
virtual void addWrite(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the write list.
GNet::EventLoop::create
static EventLoop * create()
A factory method which creates an instance of a derived class on the heap.
GNet::EventLoop::disarm
virtual void disarm(ExceptionHandler *)=0
Used to prevent the given interface from being used, typically called from the ExceptionHandler destr...
GNet::EventLoop::running
virtual bool running() const =0
Returns true if called from within run().
GNet::EventLoop::run
virtual std::string run()=0
Runs the main event loop.
geventhandler.h
gexceptionhandler.h
GNet::EventHandler
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:47
GNet::EventLoop::EventLoop
EventLoop()
Constructor.
Definition: geventloop.cpp:28
gdescriptor.h
GNet::EventLoop::Running
RAII class that sets a boolean, for implementations of run()/running().
Definition: geventloop.h:64
gexception.h
GNet::EventLoop::report
virtual std::string report() const =0
Returns a line of text reporting the status of the event loop.
GNet::EventLoop::exists
static bool exists()
Returns true if an instance exists.
Definition: geventloop.cpp:50
GNet::EventLoop::~EventLoop
virtual ~EventLoop()
Destructor.
Definition: geventloop.cpp:36
GNet::EventLoop::dropOther
virtual void dropOther(Descriptor fd)=0
Removes the given event source descriptor from the list of exception sources.
GNet::EventLoop::dropWrite
virtual void dropWrite(Descriptor fd)=0
Removes the given event source descriptor from the list of write sources.
GNet::EventLoop::addOther
virtual void addOther(Descriptor fd, EventHandler &, ExceptionHandler &)=0
Adds the given event source descriptor and associated handler to the exception list.
GNet::EventLoop::instance
static EventLoop & instance()
Returns a reference to an instance of the class, if any.
Definition: geventloop.cpp:42
GNet::EventLoop::quit
virtual void quit(std::string reason)=0
Causes run() to return (once the call stack has unwound).