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. 4 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. 9 // 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. 15 // 16 // Sample RepeatingTimer usage: 17 // 18 // class MyClass { 19 // public: 20 // void StartDoingStuff() { 21 // timer_.Start(FROM_HERE, TimeDelta::FromSeconds(1), 22 // this, &MyClass::DoStuff); 23 // } 24 // void StopDoingStuff() { 25 // timer_.Stop(); 26 // } 27 // private: 28 // void DoStuff() { 29 // // This method is called every second to do stuff. 30 // ... 31 // } 32 // base::RepeatingTimer timer_; 33 // }; 34 // 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. 41 // 42 // NOTE: These APIs are not thread safe. Always call from the same thread. 43 44 #ifndef BASE_TIMER_TIMER_H_ 45 #define BASE_TIMER_TIMER_H_ 46 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. 51 52 #include <memory> 53 54 #include "base/base_export.h" 55 #include "base/bind.h" 56 #include "base/bind_helpers.h" 57 #include "base/callback.h" 58 #include "base/location.h" 59 #include "base/macros.h" 60 #include "base/time/time.h" 61 62 namespace base { 63 64 class BaseTimerTaskInternal; 65 class SingleThreadTaskRunner; 66 class TickClock; 67 68 //----------------------------------------------------------------------------- 69 // This class wraps MessageLoop::PostDelayedTask to manage delayed and repeating 70 // tasks. It must be destructed on the same thread that starts tasks. There are 71 // DCHECKs in place to verify this. 72 // 73 class BASE_EXPORT Timer { 74 public: 75 // Construct a timer in repeating or one-shot mode. Start or SetTaskInfo must 76 // be called later to set task info. |retain_user_task| determines whether the 77 // user_task is retained or reset when it runs or stops. If |tick_clock| is 78 // provided, it is used instead of TimeTicks::Now() to get TimeTicks when 79 // scheduling tasks. 80 Timer(bool retain_user_task, bool is_repeating); 81 Timer(bool retain_user_task, bool is_repeating, TickClock* tick_clock); 82 83 // Construct a timer with retained task info. If |tick_clock| is provided, it 84 // is used instead of TimeTicks::Now() to get TimeTicks when scheduling tasks. 85 Timer(const tracked_objects::Location& posted_from, 86 TimeDelta delay, 87 const base::Closure& user_task, 88 bool is_repeating); 89 Timer(const tracked_objects::Location& posted_from, 90 TimeDelta delay, 91 const base::Closure& user_task, 92 bool is_repeating, 93 TickClock* tick_clock); 94 95 virtual ~Timer(); 96 97 // Returns true if the timer is running (i.e., not stopped). 98 virtual bool IsRunning() const; 99 100 // Returns the current delay for this timer. 101 virtual TimeDelta GetCurrentDelay() const; 102 103 // Set the task runner on which the task should be scheduled. This method can 104 // only be called before any tasks have been scheduled. The task runner must 105 // run tasks on the same thread the timer is used on. 106 virtual void SetTaskRunner(scoped_refptr<SingleThreadTaskRunner> task_runner); 107 108 // Start the timer to run at the given |delay| from now. If the timer is 109 // already running, it will be replaced to call the given |user_task|. 110 virtual void Start(const tracked_objects::Location& posted_from, 111 TimeDelta delay, 112 const base::Closure& user_task); 113 114 // Call this method to stop and cancel the timer. It is a no-op if the timer 115 // is not running. 116 virtual void Stop(); 117 118 // Call this method to reset the timer delay. The user_task_ must be set. If 119 // the timer is not running, this will start it by posting a task. 120 virtual void Reset(); 121 122 const base::Closure& user_task() const { return user_task_; } 123 const TimeTicks& desired_run_time() const { return desired_run_time_; } 124 125 protected: 126 // Returns the current tick count. 127 TimeTicks Now() const; 128 129 // Used to initiate a new delayed task. This has the side-effect of disabling 130 // scheduled_task_ if it is non-null. 131 void SetTaskInfo(const tracked_objects::Location& posted_from, 132 TimeDelta delay, 133 const base::Closure& user_task); 134 135 void set_user_task(const Closure& task) { user_task_ = task; } 136 void set_desired_run_time(TimeTicks desired) { desired_run_time_ = desired; } 137 void set_is_running(bool running) { is_running_ = running; } 138 139 const tracked_objects::Location& posted_from() const { return posted_from_; } 140 bool retain_user_task() const { return retain_user_task_; } 141 bool is_repeating() const { return is_repeating_; } 142 bool is_running() const { return is_running_; } 143 144 private: 145 friend class BaseTimerTaskInternal; 146 147 // Allocates a new scheduled_task_ and posts it on the current MessageLoop 148 // with the given |delay|. scheduled_task_ must be NULL. scheduled_run_time_ 149 // and desired_run_time_ are reset to Now() + delay. 150 void PostNewScheduledTask(TimeDelta delay); 151 152 // Returns the task runner on which the task should be scheduled. If the 153 // corresponding task_runner_ field is null, the task runner for the current 154 // thread is returned. 155 scoped_refptr<SingleThreadTaskRunner> GetTaskRunner(); 156 157 // Disable scheduled_task_ and abandon it so that it no longer refers back to 158 // this object. 159 void AbandonScheduledTask(); 160 161 // Called by BaseTimerTaskInternal when the MessageLoop runs it. 162 void RunScheduledTask(); 163 164 // Stop running task (if any) and abandon scheduled task (if any). 165 void StopAndAbandon() { 166 AbandonScheduledTask(); 167 168 Stop(); 169 // No more member accesses here: |this| could be deleted at this point. 170 } 171 172 // When non-NULL, the scheduled_task_ is waiting in the MessageLoop to call 173 // RunScheduledTask() at scheduled_run_time_. 174 BaseTimerTaskInternal* scheduled_task_; 175 176 // The task runner on which the task should be scheduled. If it is null, the 177 // task runner for the current thread should be used. 178 scoped_refptr<SingleThreadTaskRunner> task_runner_; 179 180 // Location in user code. 181 tracked_objects::Location posted_from_; 182 // Delay requested by user. 183 TimeDelta delay_; 184 // user_task_ is what the user wants to be run at desired_run_time_. 185 base::Closure user_task_; 186 187 // The estimated time that the MessageLoop will run the scheduled_task_ that 188 // will call RunScheduledTask(). This time can be a "zero" TimeTicks if the 189 // task must be run immediately. 190 TimeTicks scheduled_run_time_; 191 192 // The desired run time of user_task_. The user may update this at any time, 193 // even if their previous request has not run yet. If desired_run_time_ is 194 // greater than scheduled_run_time_, a continuation task will be posted to 195 // wait for the remaining time. This allows us to reuse the pending task so as 196 // not to flood the MessageLoop with orphaned tasks when the user code 197 // excessively Stops and Starts the timer. This time can be a "zero" TimeTicks 198 // if the task must be run immediately. 199 TimeTicks desired_run_time_; 200 201 // Thread ID of current MessageLoop for verifying single-threaded usage. 202 int thread_id_; 203 204 // Repeating timers automatically post the task again before calling the task 205 // callback. 206 const bool is_repeating_; 207 208 // If true, hold on to the user_task_ closure object for reuse. 209 const bool retain_user_task_; 210 211 // The tick clock used to calculate the run time for scheduled tasks. 212 TickClock* const tick_clock_; 213 214 // If true, user_task_ is scheduled to run sometime in the future. 215 bool is_running_; 216 217 DISALLOW_COPY_AND_ASSIGN(Timer); 218 }; 219 220 //----------------------------------------------------------------------------- 221 // This class is an implementation detail of OneShotTimer and RepeatingTimer. 222 // Please do not use this class directly. 223 class BaseTimerMethodPointer : public Timer { 224 public: 225 // This is here to work around the fact that Timer::Start is "hidden" by the 226 // Start definition below, rather than being overloaded. 227 // TODO(tim): We should remove uses of BaseTimerMethodPointer::Start below 228 // and convert callers to use the base::Closure version in Timer::Start, 229 // see bug 148832. 230 using Timer::Start; 231 232 enum RepeatMode { ONE_SHOT, REPEATING }; 233 BaseTimerMethodPointer(RepeatMode mode, TickClock* tick_clock) 234 : Timer(mode == REPEATING, mode == REPEATING, tick_clock) {} 235 236 // Start the timer to run at the given |delay| from now. If the timer is 237 // already running, it will be replaced to call a task formed from 238 // |reviewer->*method|. 239 template <class Receiver> 240 void Start(const tracked_objects::Location& posted_from, 241 TimeDelta delay, 242 Receiver* receiver, 243 void (Receiver::*method)()) { 244 Timer::Start(posted_from, delay, 245 base::Bind(method, base::Unretained(receiver))); 246 } 247 }; 248 249 //----------------------------------------------------------------------------- 250 // A simple, one-shot timer. See usage notes at the top of the file. 251 class OneShotTimer : public BaseTimerMethodPointer { 252 public: 253 OneShotTimer() : OneShotTimer(nullptr) {} 254 explicit OneShotTimer(TickClock* tick_clock) 255 : BaseTimerMethodPointer(ONE_SHOT, tick_clock) {} 256 }; 257 258 //----------------------------------------------------------------------------- 259 // A simple, repeating timer. See usage notes at the top of the file. 260 class RepeatingTimer : public BaseTimerMethodPointer { 261 public: 262 RepeatingTimer() : RepeatingTimer(nullptr) {} 263 explicit RepeatingTimer(TickClock* tick_clock) 264 : BaseTimerMethodPointer(REPEATING, tick_clock) {} 265 }; 266 267 //----------------------------------------------------------------------------- 268 // A Delay timer is like The Button from Lost. Once started, you have to keep 269 // calling Reset otherwise it will call the given method in the MessageLoop 270 // thread. 271 // 272 // Once created, it is inactive until Reset is called. Once |delay| seconds have 273 // passed since the last call to Reset, the callback is made. Once the callback 274 // has been made, it's inactive until Reset is called again. 275 // 276 // If destroyed, the timeout is canceled and will not occur even if already 277 // inflight. 278 class DelayTimer : protected Timer { 279 public: 280 template <class Receiver> 281 DelayTimer(const tracked_objects::Location& posted_from, 282 TimeDelta delay, 283 Receiver* receiver, 284 void (Receiver::*method)()) 285 : DelayTimer(posted_from, delay, receiver, method, nullptr) {} 286 287 template <class Receiver> 288 DelayTimer(const tracked_objects::Location& posted_from, 289 TimeDelta delay, 290 Receiver* receiver, 291 void (Receiver::*method)(), 292 TickClock* tick_clock) 293 : Timer(posted_from, 294 delay, 295 base::Bind(method, base::Unretained(receiver)), 296 false, 297 tick_clock) {} 298 299 void Reset() override; 300 }; 301 302 // This class has a templated method so it can not be exported without failing 303 // to link in MSVC. But clang-plugin does not allow inline definitions of 304 // virtual methods, so the inline definition lives in the header file here 305 // to satisfy both. 306 inline void DelayTimer::Reset() { 307 Timer::Reset(); 308 } 309 310 } // namespace base 311 312 #endif // BASE_TIMER_TIMER_H_ 313