E-MailRelay
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 ///
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
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
Network classes.
Definition: gaddress.h:29
TimerList()
Default constructor.
Definition: gtimerlist.cpp:32
Overload discriminator class for TimerList.
Definition: gtimerlist.h:65
A singleton which maintains a list of all Timer objects, and interfaces to the event loop on their be...
Definition: gtimerlist.h:61
void add(TimerBase &, ExceptionHandler &)
Adds a timer.
Definition: gtimerlist.cpp:45
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
static TimerList & instance()
Singleton access. Throws an exception if none.
Definition: gtimerlist.cpp:145
G::EpochTime interval(bool &infinite) const
Returns the interval to the first timer expiry.
Definition: gtimerlist.cpp:114
void doTimeouts()
Triggers the timeout callbacks of any expired timers.
Definition: gtimerlist.cpp:152
static bool exists()
Returns true if instance() exists.
Definition: gtimerlist.cpp:140
~TimerList()
Destructor. Any expired timers have their timeouts called.
Definition: gtimerlist.cpp:39
void update(TimerBase &)
Called when a timer changes its value.
Definition: gtimerlist.cpp:77
An interface used by GNet::TimerList to keep track of pending timeouts and to deliver timeout events...
Definition: gtimer.h:40
void disarm(ExceptionHandler *)
Resets any matching ExceptionHandler pointers.
Definition: gtimerlist.cpp:67
std::string report() const
Returns a line of text reporting the status of the timer list.
Definition: gtimerlist.cpp:194