E-MailRelay

gtimer.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 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 gtimer.h
19///
20
21#ifndef G_NET_TIMER_H
22#define G_NET_TIMER_H
23
24#include "gdef.h"
25#include "gdatetime.h"
26#include "geventhandler.h"
27#include "gexception.h"
28#include "geventstate.h"
29
30 namespace GNet
31{
32 class TimerBase ;
33 template <typename T> class Timer ;
34}
35
36//| \class GNet::TimerBase
37/// An interface used by GNet::TimerList to keep track of pending timeouts
38/// and to deliver timeout events. The public methods to start and cancel
39/// the timer are normally used via GNet::Timer<>.
40///
41 class GNet::TimerBase
42{
43 protected:
44 explicit TimerBase( EventState es ) ;
45 ///< Constructor. The EventState receives an onException()
46 ///< call if the onTimeout() implementation throws.
47
48 public:
49 virtual ~TimerBase() ;
50 ///< Destructor.
51
52 void startTimer( unsigned int interval_s , unsigned int interval_us = 0U ) ;
53 ///< Starts or restarts the timer so that it expires
54 ///< after the given interval.
55
56 void startTimer( const G::TimeInterval & ) ;
57 ///< Starts or restarts the timer so that it expires
58 ///< after the given interval.
59
60 void cancelTimer() ;
61 ///< Cancels the timer. Does nothing if not running.
62
63 bool active() const noexcept ;
64 ///< Returns true if the timer is started and not cancelled.
65
66 bool immediate() const ;
67 ///< Used by TimerList. Returns true if the timer is active()
68 ///< and zero-length.
69
70 void doTimeout() ;
71 ///< Used by TimerList to execute the onTimeout() callback.
72
73 G::TimerTime t() const ;
74 ///< Used by TimerList to get the expiry epoch time. Zero-length
75 ///< timers return TimerTime::zero() plus any adjust()ment,
76 ///< ~guaranteed to be less than the t() of any non-immediate
77 ///< timer.
78
79 const G::TimerTime & tref() const noexcept ;
80 ///< An inline noexcept alternative to t().
81
82 void adjust( unsigned long ) ;
83 ///< Used by TimerList to set the order of immedate() timer
84 ///< expiry.
85
86 bool expired( G::TimerTime & ) const ;
87 ///< Used by TimerList. Returns true if expired when compared
88 ///< to the given epoch time. If the given epoch time is
89 ///< TimerTime::zero() then it is initialised with
90 ///< TimerTime::now().
91
92 protected:
93 virtual void onTimeout() = 0 ;
94 ///< Called when the timer expires (or soon after).
95
96 public:
97 TimerBase( const TimerBase & ) = delete ;
98 TimerBase( TimerBase && ) = delete ;
99 TimerBase & operator=( const TimerBase & ) = delete ;
100 TimerBase & operator=( TimerBase && ) = delete ;
101
102 private:
103 static G::TimerTime history() ;
104
105 private:
106 bool m_active {false} ;
107 bool m_immediate {false} ;
108 G::TimerTime m_time ;
109} ;
110
111 inline
112 const G::TimerTime & GNet::TimerBase::tref() const noexcept
113{
114 return m_time ;
115}
116
117 inline
118 bool GNet::TimerBase::active() const noexcept
119{
120 return m_active ;
121}
122
123//| \class GNet::Timer
124/// A timer class template in which the timeout is delivered to the specified
125/// method. Any exception thrown out of the timeout handler is delivered to
126/// the specified ExceptionHandler interface so that it can be handled or
127/// rethrown.
128///
129/// Eg:
130/// \code
131/// struct Foo
132/// {
133/// Timer<Foo> m_timer ;
134/// Foo( EventState es ) : m_timer(*this,&Foo::onTimeout,es) {}
135/// void onTimeout() { throw "oops" ; }
136/// } ;
137/// \endcode
138///
139 template <typename T>
140 class GNet::Timer : private TimerBase
141{
142 public:
143 using method_type = void (T::*)() ;
144
145 Timer( T & t , method_type m , EventState ) ;
146 ///< Constructor.
147
148 void startTimer( unsigned int interval_s , unsigned int interval_us = 0U ) ;
149 ///< Starts or restarts the timer so that it expires
150 ///< after the given interval.
151
152 void startTimer( const G::TimeInterval & ) ;
153 ///< Starts or restarts the timer so that it expires
154 ///< after the given interval.
155
156 void cancelTimer() ;
157 ///< Cancels the timer. Does nothing if not running.
158
159 bool active() const noexcept ;
160 ///< Returns true if the timer is running.
161
162public:
163 ~Timer() override = default ;
164 Timer( const Timer<T> & ) = delete ;
165 Timer( Timer<T> && ) = delete ;
166 Timer<T> & operator=( const Timer<T> & ) = delete ;
167 Timer<T> & operator=( Timer<T> && ) = delete ;
168
169private: // overrides
170 void onTimeout() override ; // Override from GNet::TimerBase.
171
172private:
173 T & m_t ; // callback target object
174 method_type m_m ;
175} ;
176
177template <typename T>
178 GNet::Timer<T>::Timer( T & t , method_type m , GNet::EventState es ) :
179 TimerBase(es) ,
180 m_t(t) ,
181 m_m(m)
182{
183}
184
185 template <typename T>
186 void GNet::Timer<T>::startTimer( unsigned int s , unsigned int us )
187{
188 TimerBase::startTimer( s , us ) ;
189}
190
191 template <typename T>
192 void GNet::Timer<T>::startTimer( const G::TimeInterval & i )
193{
194 TimerBase::startTimer( i ) ;
195}
196
197 template <typename T>
198 void GNet::Timer<T>::cancelTimer()
199{
200 TimerBase::cancelTimer() ;
201}
202
203 template <typename T>
204 void GNet::Timer<T>::onTimeout()
205{
206 (m_t.*m_m)() ;
207}
208
209 template <typename T>
210 bool GNet::Timer<T>::active() const noexcept
211{
212 return TimerBase::active() ;
213}
214
215#endif
GNet::EventState
A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and opt...
Definition: geventstate.h:131
GNet::TimerBase
An interface used by GNet::TimerList to keep track of pending timeouts and to deliver timeout events.
Definition: gtimer.h:42
GNet::TimerBase::doTimeout
void doTimeout()
Used by TimerList to execute the onTimeout() callback.
Definition: gtimer.cpp:105
GNet::TimerBase::adjust
void adjust(unsigned long)
Used by TimerList to set the order of immedate() timer expiry.
Definition: gtimer.cpp:90
GNet::TimerBase::immediate
bool immediate() const
Used by TimerList.
Definition: gtimer.cpp:85
GNet::TimerBase::cancelTimer
void cancelTimer()
Cancels the timer. Does nothing if not running.
Definition: gtimer.cpp:96
GNet::TimerBase::onTimeout
virtual void onTimeout()=0
Called when the timer expires (or soon after).
GNet::TimerBase::startTimer
void startTimer(unsigned int interval_s, unsigned int interval_us=0U)
Starts or restarts the timer so that it expires after the given interval.
Definition: gtimer.cpp:69
GNet::TimerBase::expired
bool expired(G::TimerTime &) const
Used by TimerList.
Definition: gtimer.cpp:47
GNet::TimerBase::tref
const G::TimerTime & tref() const noexcept
An inline noexcept alternative to t().
Definition: gtimer.h:112
GNet::TimerBase::TimerBase
TimerBase(EventState es)
Constructor.
Definition: gtimer.cpp:29
GNet::TimerBase::active
bool active() const noexcept
Returns true if the timer is started and not cancelled.
Definition: gtimer.h:118
GNet::TimerBase::t
G::TimerTime t() const
Used by TimerList to get the expiry epoch time.
Definition: gtimer.cpp:112
GNet::TimerBase::~TimerBase
virtual ~TimerBase()
Destructor.
Definition: gtimer.cpp:35
GNet::Timer
A timer class template in which the timeout is delivered to the specified method.
Definition: gtimer.h:141
GNet::Timer::startTimer
void startTimer(unsigned int interval_s, unsigned int interval_us=0U)
Starts or restarts the timer so that it expires after the given interval.
Definition: gtimer.h:186
GNet::Timer::startTimer
void startTimer(const G::TimeInterval &)
Starts or restarts the timer so that it expires after the given interval.
Definition: gtimer.h:192
GNet::Timer::cancelTimer
void cancelTimer()
Cancels the timer. Does nothing if not running.
Definition: gtimer.h:198
GNet::Timer::Timer
Timer(T &t, method_type m, EventState)
Constructor.
Definition: gtimer.h:178
GNet::Timer::active
bool active() const noexcept
Returns true if the timer is running.
Definition: gtimer.h:210
G::TimeInterval
An interval between two G::SystemTime values or two G::TimerTime values.
Definition: gdatetime.h:305
G::TimerTime
A monotonically increasing subsecond-resolution timestamp, notionally unrelated to time_t.
Definition: gdatetime.h:231
gdatetime.h
geventhandler.h
geventstate.h
gexception.h
GNet
Network classes.
Definition: gdef.h:1243