1 // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // OneShotTimer and RepeatingTimer provide a simple timer API. As the names
6 // suggest, OneShotTimer calls you back once after a time delay expires.
7 // RepeatingTimer on the other hand calls you back periodically with the
8 // prescribed time interval.
10 // OneShotTimer and RepeatingTimer both cancel the timer when they go out of
11 // scope, which makes it easy to ensure that you do not get called when your
12 // object has gone out of scope. Just instantiate a OneShotTimer or
13 // RepeatingTimer as a member variable of the class for which you wish to
14 // receive timer events.
16 // Sample RepeatingTimer usage:
20 // void StartDoingStuff() {
21 // timer_.Start(TimeDelta::FromSeconds(1), this, &MyClass::DoStuff);
23 // void StopDoingStuff() {
28 // // This method is called every second to do stuff.
31 // base::RepeatingTimer<MyClass> timer_;
34 // Both OneShotTimer and RepeatingTimer also support a Reset method, which
35 // allows you to easily defer the timer event until the timer delay passes once
36 // again. So, in the above example, if 0.5 seconds have already passed,
37 // calling Reset on timer_ would postpone DoStuff by another 1 second. In
38 // other words, Reset is shorthand for calling Stop and then Start again with
39 // the same arguments.
44 // IMPORTANT: If you change timer code, make sure that all tests (including
45 // disabled ones) from timer_unittests.cc pass locally. Some are disabled
46 // because they're flaky on the buildbot, but when you run them locally you
47 // should be able to tell the difference.
49 #include "base/logging.h"
50 #include "base/task.h"
51 #include "base/time.h"
57 //-----------------------------------------------------------------------------
58 // This class is an implementation detail of OneShotTimer and RepeatingTimer.
59 // Please do not use this class directly.
61 // This class exists to share code between BaseTimer<T> template instantiations.
63 class BaseTimer_Helper
{
70 // Returns true if the timer is running (i.e., not stopped).
71 bool IsRunning() const {
72 return delayed_task_
!= NULL
;
75 // Returns the current delay for this timer. May only call this method when
76 // the timer is running!
77 TimeDelta
GetCurrentDelay() const {
79 return delayed_task_
->delay_
;
83 BaseTimer_Helper() : delayed_task_(NULL
) {}
85 // We have access to the timer_ member so we can orphan this task.
86 class TimerTask
: public Task
{
88 explicit TimerTask(TimeDelta delay
) : timer_(NULL
), delay_(delay
) {
90 virtual ~TimerTask() {}
91 BaseTimer_Helper
* timer_
;
95 // Used to orphan delayed_task_ so that when it runs it does nothing.
96 void OrphanDelayedTask();
98 // Used to initiated a new delayed task. This has the side-effect of
99 // orphaning delayed_task_ if it is non-null.
100 void InitiateDelayedTask(TimerTask
* timer_task
);
102 TimerTask
* delayed_task_
;
104 DISALLOW_COPY_AND_ASSIGN(BaseTimer_Helper
);
107 //-----------------------------------------------------------------------------
108 // This class is an implementation detail of OneShotTimer and RepeatingTimer.
109 // Please do not use this class directly.
110 template <class Receiver
, bool kIsRepeating
>
111 class BaseTimer
: public BaseTimer_Helper
{
113 typedef void (Receiver::*ReceiverMethod
)();
115 // Call this method to start the timer. It is an error to call this method
116 // while the timer is already running.
117 void Start(TimeDelta delay
, Receiver
* receiver
, ReceiverMethod method
) {
118 DCHECK(!IsRunning());
119 InitiateDelayedTask(new TimerTask(delay
, receiver
, method
));
122 // Call this method to stop the timer. It is a no-op if the timer is not
128 // Call this method to reset the timer delay of an already running timer.
131 InitiateDelayedTask(static_cast<TimerTask
*>(delayed_task_
)->Clone());
135 typedef BaseTimer
<Receiver
, kIsRepeating
> SelfType
;
137 class TimerTask
: public BaseTimer_Helper::TimerTask
{
139 TimerTask(TimeDelta delay
, Receiver
* receiver
, ReceiverMethod method
)
140 : BaseTimer_Helper::TimerTask(delay
),
145 virtual ~TimerTask() {
146 // This task may be getting cleared because the MessageLoop has been
147 // destructed. If so, don't leave the Timer with a dangling pointer
148 // to this now-defunct task.
153 if (!timer_
) // timer_ is null if we were orphaned.
159 DispatchToMethod(receiver_
, method_
, Tuple0());
162 TimerTask
* Clone() const {
163 return new TimerTask(delay_
, receiver_
, method_
);
167 // Inform the Base that the timer is no longer active.
168 void ClearBaseTimer() {
170 SelfType
* self
= static_cast<SelfType
*>(timer_
);
171 // It is possible that the Timer has already been reset, and that this
172 // Task is old. So, if the Timer points to a different task, assume
173 // that the Timer has already taken care of properly setting the task.
174 if (self
->delayed_task_
== this)
175 self
->delayed_task_
= NULL
;
176 // By now the delayed_task_ in the Timer does not point to us anymore.
177 // We should reset our own timer_ because the Timer can not do this
178 // for us in its destructor.
183 // Inform the Base that we're resetting the timer.
184 void ResetBaseTimer() {
186 DCHECK(kIsRepeating
);
187 SelfType
* self
= static_cast<SelfType
*>(timer_
);
192 ReceiverMethod method_
;
196 //-----------------------------------------------------------------------------
197 // A simple, one-shot timer. See usage notes at the top of the file.
198 template <class Receiver
>
199 class OneShotTimer
: public BaseTimer
<Receiver
, false> {};
201 //-----------------------------------------------------------------------------
202 // A simple, repeating timer. See usage notes at the top of the file.
203 template <class Receiver
>
204 class RepeatingTimer
: public BaseTimer
<Receiver
, true> {};
206 //-----------------------------------------------------------------------------
207 // A Delay timer is like The Button from Lost. Once started, you have to keep
208 // calling Reset otherwise it will call the given method in the MessageLoop
211 // Once created, it is inactive until Reset is called. Once |delay| seconds have
212 // passed since the last call to Reset, the callback is made. Once the callback
213 // has been made, it's inactive until Reset is called again.
215 // If destroyed, the timeout is canceled and will not occur even if already
217 template <class Receiver
>
220 typedef void (Receiver::*ReceiverMethod
)();
222 DelayTimer(TimeDelta delay
, Receiver
* receiver
, ReceiverMethod method
)
223 : receiver_(receiver
),
233 void DelayFor(TimeDelta delay
) {
234 trigger_time_
= Time::Now() + delay
;
236 // If we already have a timer that will expire at or before the given delay,
237 // then we have nothing more to do now.
238 if (timer_
.IsRunning() && timer_
.GetCurrentDelay() <= delay
)
241 // The timer isn't running, or will expire too late, so restart it.
243 timer_
.Start(delay
, this, &DelayTimer
<Receiver
>::Check
);
247 if (trigger_time_
.is_null())
250 // If we have not waited long enough, then wait some more.
251 const Time now
= Time::Now();
252 if (now
< trigger_time_
) {
253 DelayFor(trigger_time_
- now
);
257 (receiver_
->*method_
)();
260 Receiver
*const receiver_
;
261 const ReceiverMethod method_
;
262 const TimeDelta delay_
;
264 OneShotTimer
<DelayTimer
<Receiver
> > timer_
;
270 #endif // BASE_TIMER_H_