1 // Copyright (c) 2012 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(FROM_HERE, TimeDelta::FromSeconds(1),
22 // this, &MyClass::DoStuff);
24 // void StopDoingStuff() {
29 // // This method is called every second to do stuff.
32 // base::RepeatingTimer<MyClass> timer_;
35 // Both OneShotTimer and RepeatingTimer also support a Reset method, which
36 // allows you to easily defer the timer event until the timer delay passes once
37 // again. So, in the above example, if 0.5 seconds have already passed,
38 // calling Reset on timer_ would postpone DoStuff by another 1 second. In
39 // other words, Reset is shorthand for calling Stop and then Start again with
40 // the same arguments.
42 // NOTE: These APIs are not thread safe. Always call from the same thread.
44 #ifndef BASE_TIMER_TIMER_H_
45 #define BASE_TIMER_TIMER_H_
47 // IMPORTANT: If you change timer code, make sure that all tests (including
48 // disabled ones) from timer_unittests.cc pass locally. Some are disabled
49 // because they're flaky on the buildbot, but when you run them locally you
50 // should be able to tell the difference.
52 #include "base/base_export.h"
53 #include "base/basictypes.h"
54 #include "base/bind.h"
55 #include "base/bind_helpers.h"
56 #include "base/callback.h"
57 #include "base/location.h"
58 #include "base/time/time.h"
62 class BaseTimerTaskInternal
;
63 class SingleThreadTaskRunner
;
65 //-----------------------------------------------------------------------------
66 // This class wraps MessageLoop::PostDelayedTask to manage delayed and repeating
67 // tasks. It must be destructed on the same thread that starts tasks. There are
68 // DCHECKs in place to verify this.
70 class BASE_EXPORT Timer
{
72 // Construct a timer in repeating or one-shot mode. Start or SetTaskInfo must
73 // be called later to set task info. |retain_user_task| determines whether the
74 // user_task is retained or reset when it runs or stops.
75 Timer(bool retain_user_task
, bool is_repeating
);
77 // Construct a timer with retained task info.
78 Timer(const tracked_objects::Location
& posted_from
,
80 const base::Closure
& user_task
,
85 // Returns true if the timer is running (i.e., not stopped).
86 virtual bool IsRunning() const;
88 // Returns the current delay for this timer.
89 virtual TimeDelta
GetCurrentDelay() const;
91 // Set the task runner on which the task should be scheduled. This method can
92 // only be called before any tasks have been scheduled.
93 virtual void SetTaskRunner(scoped_refptr
<SingleThreadTaskRunner
> task_runner
);
95 // Start the timer to run at the given |delay| from now. If the timer is
96 // already running, it will be replaced to call the given |user_task|.
97 virtual void Start(const tracked_objects::Location
& posted_from
,
99 const base::Closure
& user_task
);
101 // Call this method to stop and cancel the timer. It is a no-op if the timer
105 // Call this method to reset the timer delay. The user_task_ must be set. If
106 // the timer is not running, this will start it by posting a task.
107 virtual void Reset();
109 const base::Closure
& user_task() const { return user_task_
; }
110 const TimeTicks
& desired_run_time() const { return desired_run_time_
; }
113 // Used to initiate a new delayed task. This has the side-effect of disabling
114 // scheduled_task_ if it is non-null.
115 void SetTaskInfo(const tracked_objects::Location
& posted_from
,
117 const base::Closure
& user_task
);
119 void set_user_task(const Closure
& task
) { user_task_
= task
; }
120 void set_desired_run_time(TimeTicks desired
) { desired_run_time_
= desired
; }
121 void set_is_running(bool running
) { is_running_
= running
; }
123 const tracked_objects::Location
& posted_from() const { return posted_from_
; }
124 bool retain_user_task() const { return retain_user_task_
; }
125 bool is_repeating() const { return is_repeating_
; }
126 bool is_running() const { return is_running_
; }
129 friend class BaseTimerTaskInternal
;
131 // Allocates a new scheduled_task_ and posts it on the current MessageLoop
132 // with the given |delay|. scheduled_task_ must be NULL. scheduled_run_time_
133 // and desired_run_time_ are reset to Now() + delay.
134 void PostNewScheduledTask(TimeDelta delay
);
136 // Returns the task runner on which the task should be scheduled. If the
137 // corresponding task_runner_ field is null, the task runner for the current
138 // thread is returned.
139 scoped_refptr
<SingleThreadTaskRunner
> GetTaskRunner();
141 // Disable scheduled_task_ and abandon it so that it no longer refers back to
143 void AbandonScheduledTask();
145 // Called by BaseTimerTaskInternal when the MessageLoop runs it.
146 void RunScheduledTask();
148 // Stop running task (if any) and abandon scheduled task (if any).
149 void StopAndAbandon() {
151 AbandonScheduledTask();
154 // When non-NULL, the scheduled_task_ is waiting in the MessageLoop to call
155 // RunScheduledTask() at scheduled_run_time_.
156 BaseTimerTaskInternal
* scheduled_task_
;
158 // The task runner on which the task should be scheduled. If it is null, the
159 // task runner for the current thread should be used.
160 scoped_refptr
<SingleThreadTaskRunner
> task_runner_
;
162 // Location in user code.
163 tracked_objects::Location posted_from_
;
164 // Delay requested by user.
166 // user_task_ is what the user wants to be run at desired_run_time_.
167 base::Closure user_task_
;
169 // The estimated time that the MessageLoop will run the scheduled_task_ that
170 // will call RunScheduledTask(). This time can be a "zero" TimeTicks if the
171 // task must be run immediately.
172 TimeTicks scheduled_run_time_
;
174 // The desired run time of user_task_. The user may update this at any time,
175 // even if their previous request has not run yet. If desired_run_time_ is
176 // greater than scheduled_run_time_, a continuation task will be posted to
177 // wait for the remaining time. This allows us to reuse the pending task so as
178 // not to flood the MessageLoop with orphaned tasks when the user code
179 // excessively Stops and Starts the timer. This time can be a "zero" TimeTicks
180 // if the task must be run immediately.
181 TimeTicks desired_run_time_
;
183 // Thread ID of current MessageLoop for verifying single-threaded usage.
186 // Repeating timers automatically post the task again before calling the task
188 const bool is_repeating_
;
190 // If true, hold on to the user_task_ closure object for reuse.
191 const bool retain_user_task_
;
193 // If true, user_task_ is scheduled to run sometime in the future.
196 DISALLOW_COPY_AND_ASSIGN(Timer
);
199 //-----------------------------------------------------------------------------
200 // This class is an implementation detail of OneShotTimer and RepeatingTimer.
201 // Please do not use this class directly.
202 template <class Receiver
, bool kIsRepeating
>
203 class BaseTimerMethodPointer
: public Timer
{
205 typedef void (Receiver::*ReceiverMethod
)();
207 // This is here to work around the fact that Timer::Start is "hidden" by the
208 // Start definition below, rather than being overloaded.
209 // TODO(tim): We should remove uses of BaseTimerMethodPointer::Start below
210 // and convert callers to use the base::Closure version in Timer::Start,
214 BaseTimerMethodPointer() : Timer(kIsRepeating
, kIsRepeating
) {}
216 // Start the timer to run at the given |delay| from now. If the timer is
217 // already running, it will be replaced to call a task formed from
218 // |reviewer->*method|.
219 virtual void Start(const tracked_objects::Location
& posted_from
,
222 ReceiverMethod method
) {
223 Timer::Start(posted_from
, delay
,
224 base::Bind(method
, base::Unretained(receiver
)));
228 //-----------------------------------------------------------------------------
229 // A simple, one-shot timer. See usage notes at the top of the file.
230 template <class Receiver
>
231 class OneShotTimer
: public BaseTimerMethodPointer
<Receiver
, false> {};
233 //-----------------------------------------------------------------------------
234 // A simple, repeating timer. See usage notes at the top of the file.
235 template <class Receiver
>
236 class RepeatingTimer
: public BaseTimerMethodPointer
<Receiver
, true> {};
238 //-----------------------------------------------------------------------------
239 // A Delay timer is like The Button from Lost. Once started, you have to keep
240 // calling Reset otherwise it will call the given method in the MessageLoop
243 // Once created, it is inactive until Reset is called. Once |delay| seconds have
244 // passed since the last call to Reset, the callback is made. Once the callback
245 // has been made, it's inactive until Reset is called again.
247 // If destroyed, the timeout is canceled and will not occur even if already
249 template <class Receiver
>
250 class DelayTimer
: protected Timer
{
252 typedef void (Receiver::*ReceiverMethod
)();
254 DelayTimer(const tracked_objects::Location
& posted_from
,
257 ReceiverMethod method
)
258 : Timer(posted_from
, delay
,
259 base::Bind(method
, base::Unretained(receiver
)),
262 void Reset() override
{ Timer::Reset(); }
267 #endif // BASE_TIMER_TIMER_H_