src/base/timer/timer.h

   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<MyClass> 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 "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"
  59
  60 namespace base {
  61
  62 class BaseTimerTaskInternal;
  63
  64 //-----------------------------------------------------------------------------
  65 // This class wraps MessageLoop::PostDelayedTask to manage delayed and repeating
  66 // tasks. It must be destructed on the same thread that starts tasks. There are
  67 // DCHECKs in place to verify this.
  68 //
  69 class BASE_EXPORT Timer {
  70  public:
  71   // Construct a timer in repeating or one-shot mode. Start or SetTaskInfo must
  72   // be called later to set task info. |retain_user_task| determines whether the
  73   // user_task is retained or reset when it runs or stops.
  74   Timer(bool retain_user_task, bool is_repeating);
  75
  76   // Construct a timer with retained task info.
  77   Timer(const tracked_objects::Location& posted_from,
  78         TimeDelta delay,
  79         const base::Closure& user_task,
  80         bool is_repeating);
  81
  82   virtual ~Timer();
  83
  84   // Returns true if the timer is running (i.e., not stopped).
  85   bool IsRunning() const {
  86     return is_running_;
  87   }
  88
  89   // Returns the current delay for this timer.
  90   TimeDelta GetCurrentDelay() const {
  91     return delay_;
  92   }
  93
  94   // Start the timer to run at the given |delay| from now. If the timer is
  95   // already running, it will be replaced to call the given |user_task|.
  96   void Start(const tracked_objects::Location& posted_from,
  97              TimeDelta delay,
  98              const base::Closure& user_task);
  99
 100   // Call this method to stop and cancel the timer.  It is a no-op if the timer
 101   // is not running.
 102   void Stop();
 103
 104   // Call this method to reset the timer delay. The user_task_ must be set. If
 105   // the timer is not running, this will start it by posting a task.
 106   void Reset();
 107
 108   const base::Closure& user_task() const { return user_task_; }
 109   const TimeTicks& desired_run_time() const { return desired_run_time_; }
 110
 111  protected:
 112   // Used to initiate a new delayed task.  This has the side-effect of disabling
 113   // scheduled_task_ if it is non-null.
 114   void SetTaskInfo(const tracked_objects::Location& posted_from,
 115                    TimeDelta delay,
 116                    const base::Closure& user_task);
 117
 118  private:
 119   friend class BaseTimerTaskInternal;
 120
 121   // Allocates a new scheduled_task_ and posts it on the current MessageLoop
 122   // with the given |delay|. scheduled_task_ must be NULL. scheduled_run_time_
 123   // and desired_run_time_ are reset to Now() + delay.
 124   void PostNewScheduledTask(TimeDelta delay);
 125
 126   // Disable scheduled_task_ and abandon it so that it no longer refers back to
 127   // this object.
 128   void AbandonScheduledTask();
 129
 130   // Called by BaseTimerTaskInternal when the MessageLoop runs it.
 131   void RunScheduledTask();
 132
 133   // Stop running task (if any) and abandon scheduled task (if any).
 134   void StopAndAbandon() {
 135     Stop();
 136     AbandonScheduledTask();
 137   }
 138
 139   // When non-NULL, the scheduled_task_ is waiting in the MessageLoop to call
 140   // RunScheduledTask() at scheduled_run_time_.
 141   BaseTimerTaskInternal* scheduled_task_;
 142
 143   // Location in user code.
 144   tracked_objects::Location posted_from_;
 145   // Delay requested by user.
 146   TimeDelta delay_;
 147   // user_task_ is what the user wants to be run at desired_run_time_.
 148   base::Closure user_task_;
 149
 150   // The estimated time that the MessageLoop will run the scheduled_task_ that
 151   // will call RunScheduledTask().
 152   TimeTicks scheduled_run_time_;
 153
 154   // The desired run time of user_task_. The user may update this at any time,
 155   // even if their previous request has not run yet. If desired_run_time_ is
 156   // greater than scheduled_run_time_, a continuation task will be posted to
 157   // wait for the remaining time. This allows us to reuse the pending task so as
 158   // not to flood the MessageLoop with orphaned tasks when the user code
 159   // excessively Stops and Starts the timer.
 160   TimeTicks desired_run_time_;
 161
 162   // Thread ID of current MessageLoop for verifying single-threaded usage.
 163   int thread_id_;
 164
 165   // Repeating timers automatically post the task again before calling the task
 166   // callback.
 167   const bool is_repeating_;
 168
 169   // If true, hold on to the user_task_ closure object for reuse.
 170   const bool retain_user_task_;
 171
 172   // If true, user_task_ is scheduled to run sometime in the future.
 173   bool is_running_;
 174
 175   DISALLOW_COPY_AND_ASSIGN(Timer);
 176 };
 177
 178 //-----------------------------------------------------------------------------
 179 // This class is an implementation detail of OneShotTimer and RepeatingTimer.
 180 // Please do not use this class directly.
 181 template <class Receiver, bool kIsRepeating>
 182 class BaseTimerMethodPointer : public Timer {
 183  public:
 184   typedef void (Receiver::*ReceiverMethod)();
 185
 186   // This is here to work around the fact that Timer::Start is "hidden" by the
 187   // Start definition below, rather than being overloaded.
 188   // TODO(tim): We should remove uses of BaseTimerMethodPointer::Start below
 189   // and convert callers to use the base::Closure version in Timer::Start,
 190   // see bug 148832.
 191   using Timer::Start;
 192
 193   BaseTimerMethodPointer() : Timer(kIsRepeating, kIsRepeating) {}
 194
 195   // Start the timer to run at the given |delay| from now. If the timer is
 196   // already running, it will be replaced to call a task formed from
 197   // |reviewer->*method|.
 198   void Start(const tracked_objects::Location& posted_from,
 199              TimeDelta delay,
 200              Receiver* receiver,
 201              ReceiverMethod method) {
 202     Timer::Start(posted_from, delay,
 203                  base::Bind(method, base::Unretained(receiver)));
 204   }
 205 };
 206
 207 //-----------------------------------------------------------------------------
 208 // A simple, one-shot timer.  See usage notes at the top of the file.
 209 template <class Receiver>
 210 class OneShotTimer : public BaseTimerMethodPointer<Receiver, false> {};
 211
 212 //-----------------------------------------------------------------------------
 213 // A simple, repeating timer.  See usage notes at the top of the file.
 214 template <class Receiver>
 215 class RepeatingTimer : public BaseTimerMethodPointer<Receiver, true> {};
 216
 217 //-----------------------------------------------------------------------------
 218 // A Delay timer is like The Button from Lost. Once started, you have to keep
 219 // calling Reset otherwise it will call the given method in the MessageLoop
 220 // thread.
 221 //
 222 // Once created, it is inactive until Reset is called. Once |delay| seconds have
 223 // passed since the last call to Reset, the callback is made. Once the callback
 224 // has been made, it's inactive until Reset is called again.
 225 //
 226 // If destroyed, the timeout is canceled and will not occur even if already
 227 // inflight.
 228 template <class Receiver>
 229 class DelayTimer : protected Timer {
 230  public:
 231   typedef void (Receiver::*ReceiverMethod)();
 232
 233   DelayTimer(const tracked_objects::Location& posted_from,
 234              TimeDelta delay,
 235              Receiver* receiver,
 236              ReceiverMethod method)
 237       : Timer(posted_from, delay,
 238               base::Bind(method, base::Unretained(receiver)),
 239               false) {}
 240
 241   void Reset() { Timer::Reset(); }
 242 };
 243
 244 }  // namespace base
 245
 246 #endif  // BASE_TIMER_TIMER_H_