E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

gtimerlist.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 gtimerlist.h
19 ///
20
21 #ifndef G_NET_TIMER_LIST__H
22 #define G_NET_TIMER_LIST__H
23
24 #include "gdef.h"
25 #include "gdatetime.h"
26 #include "geventhandler.h"
27 #include "gexception.h"
28 #include <list>
29
30 namespace GNet
31 {
32 class TimerList ;
33 class TimerBase ;
34 }
35
36 /// \class GNet::TimerList
37 /// A singleton which maintains a list of all Timer objects, and interfaces
38 /// to the event loop on their behalf.
39 ///
40 /// Event loops that can do a timed-wait should call TimerList::interval()
41 /// to determine how long to wait before the first G::Timer goes off.
42 /// If the timed-wait times-out or if the interval was zero then they must
43 /// call TimerList::doTimeouts().
44 ///
45 /// Event loops that cannot do timed waits efficiently (ie. the traditional
46 /// Windows message queue) have their setTimeout() method called by this
47 /// class and they are expected to call doTimeouts() when the event-loop
48 /// timer expires.
49 ///
50 /// In both models there can be a race where this class sees no expired
51 /// timers in doTimeouts(), perhaps because the system clock is being
52 /// stretched. However, the next interval() or setTimer() time will be
53 /// very small and the race will resolve itself naturally.
54 ///
55 /// If a timer callback throws an exception then the associated
56 /// exception handler is called. This is the same behaviour as in the
57 /// EventHandlerList. This is made safe even if the event handler object
58 /// is destroyed by the original exception because of the disarm()
59 /// mechanism.
60 ///
61 class GNet::TimerList
62 {
63 public:
64 G_EXCEPTION( NoInstance , "no TimerList instance" ) ;
65 class NoThrow /// Overload discriminator class for TimerList.
66 {} ;
67
68 TimerList() ;
69 ///< Default constructor.
70
71 ~TimerList() ;
72 ///< Destructor. Any expired timers have their timeouts called.
73
74 void add( TimerBase & , ExceptionHandler & ) ;
75 ///< Adds a timer.
76
77 void remove( TimerBase & ) ;
78 ///< Removes a timer from the list.
79
80 void update( TimerBase & ) ;
81 ///< Called when a timer changes its value.
82
83 G::EpochTime interval( bool & infinite ) const ;
84 ///< Returns the interval to the first timer expiry. The 'infinite'
85 ///< value is set to true if there are no timers running.
86
87 void doTimeouts() ;
88 ///< Triggers the timeout callbacks of any expired timers.
89 ///< Called by the event loop (GNet::EventLoop).
90
91 static bool exists() ;
92 ///< Returns true if instance() exists.
93
94 static TimerList * instance( const NoThrow & ) ;
95 ///< Singleton access. Returns nullptr if none.
96
97 static TimerList & instance() ;
98 ///< Singleton access. Throws an exception if none.
99
100 std::string report() const ;
101 ///< Returns a line of text reporting the status of the timer list.
102 ///< Used in debugging and diagnostics.
103
104 void disarm( ExceptionHandler * ) ;
105 ///< Resets any matching ExceptionHandler pointers.
106
107 private:
108 TimerList( const TimerList & ) ;
109 void operator=( const TimerList & ) ;
110 G::EpochTime soonestTime() const ;
111 TimerBase * findSoonest() ;
112 void collectGarbage() ;
113 void setTimeout() ;
114
115 private:
116 struct Value /// A value type for the GNet::TimerList.
117 {
118 TimerBase * first ;
119 ExceptionHandler * second ;
120 Value( TimerBase * t , ExceptionHandler *eh ) : first(t) , second(eh) {}
121 } ;
122 typedef std::list<Value> List ;
123 static TimerList * m_this ;
124 TimerBase * m_soonest ;
125 List m_list ;
126 } ;
127
128 #endif
G::EpochTime
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
GNet
Network classes.
Definition: gaddress.h:29
GNet::TimerList::TimerList
TimerList()
Default constructor.
Definition: gtimerlist.cpp:32
GNet::TimerList::NoThrow
Overload discriminator class for TimerList.
Definition: gtimerlist.h:65
GNet::TimerList
A singleton which maintains a list of all Timer objects, and interfaces to the event loop on their be...
Definition: gtimerlist.h:61
GNet::TimerList::add
void add(TimerBase &, ExceptionHandler &)
Adds a timer.
Definition: gtimerlist.cpp:45
GNet::ExceptionHandler
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
Definition: gexceptionhandler.h:44
GNet::TimerList::instance
static TimerList & instance()
Singleton access. Throws an exception if none.
Definition: gtimerlist.cpp:145
GNet::TimerList::interval
G::EpochTime interval(bool &infinite) const
Returns the interval to the first timer expiry.
Definition: gtimerlist.cpp:114
GNet::TimerList::doTimeouts
void doTimeouts()
Triggers the timeout callbacks of any expired timers.
Definition: gtimerlist.cpp:152
geventhandler.h
GNet::TimerList::exists
static bool exists()
Returns true if instance() exists.
Definition: gtimerlist.cpp:140
gdatetime.h
GNet::TimerList::~TimerList
~TimerList()
Destructor. Any expired timers have their timeouts called.
Definition: gtimerlist.cpp:39
gexception.h
GNet::TimerList::update
void update(TimerBase &)
Called when a timer changes its value.
Definition: gtimerlist.cpp:77
GNet::TimerBase
An interface used by GNet::TimerList to keep track of pending timeouts and to deliver timeout events...
Definition: gtimer.h:40
GNet::TimerList::disarm
void disarm(ExceptionHandler *)
Resets any matching ExceptionHandler pointers.
Definition: gtimerlist.cpp:67
GNet::TimerList::report
std::string report() const
Returns a line of text reporting the status of the timer list.
Definition: gtimerlist.cpp:194