base/threading/watchdog.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 // The Watchdog class creates a second thread that can Alarm if a specific
   6 // duration of time passes without proper attention.  The duration of time is
   7 // specified at construction time.  The Watchdog may be used many times by
   8 // simply calling Arm() (to start timing) and Disarm() (to reset the timer).
   9 // The Watchdog is typically used under a debugger, where the stack traces on
  10 // other threads can be examined if/when the Watchdog alarms.
  11
  12 // Some watchdogs will be enabled or disabled via command line switches. To
  13 // facilitate such code, an "enabled" argument for the constuctor can be used
  14 // to permanently disable the watchdog.  Disabled watchdogs don't even spawn
  15 // a second thread, and their methods call (Arm() and Disarm()) return very
  16 // quickly.
  17
  18 #ifndef BASE_THREADING_WATCHDOG_H_
  19 #define BASE_THREADING_WATCHDOG_H_
  20
  21 #include <string>
  22
  23 #include "base/base_export.h"
  24 #include "base/compiler_specific.h"
  25 #include "base/synchronization/condition_variable.h"
  26 #include "base/synchronization/lock.h"
  27 #include "base/threading/platform_thread.h"
  28 #include "base/time/time.h"
  29
  30 namespace base {
  31
  32 class BASE_EXPORT Watchdog {
  33  public:
  34   // Constructor specifies how long the Watchdog will wait before alarming.
  35   Watchdog(const TimeDelta& duration,
  36            const std::string& thread_watched_name,
  37            bool enabled);
  38   virtual ~Watchdog();
  39
  40   // Notify watchdog thread to finish up. Sets the state_ to SHUTDOWN.
  41   void Cleanup();
  42
  43   // Returns true if we state_ is JOINABLE (which indicates that Watchdog has
  44   // exited).
  45   bool IsJoinable();
  46
  47   // Start timing, and alarm when time expires (unless we're disarm()ed.)
  48   void Arm();  // Arm  starting now.
  49   void ArmSomeTimeDeltaAgo(const TimeDelta& time_delta);
  50   void ArmAtStartTime(const TimeTicks start_time);
  51
  52   // Reset time, and do not set off the alarm.
  53   void Disarm();
  54
  55   // Alarm is called if the time expires after an Arm() without someone calling
  56   // Disarm().  This method can be overridden to create testable classes.
  57   virtual void Alarm();
  58
  59   // Reset static data to initial state. Useful for tests, to ensure
  60   // they are independent.
  61   static void ResetStaticData();
  62
  63  private:
  64   class ThreadDelegate : public PlatformThread::Delegate {
  65    public:
  66     explicit ThreadDelegate(Watchdog* watchdog) : watchdog_(watchdog) {
  67     }
  68     void ThreadMain() override;
  69
  70    private:
  71     void SetThreadName() const;
  72
  73     Watchdog* watchdog_;
  74   };
  75
  76   enum State {ARMED, DISARMED, SHUTDOWN, JOINABLE };
  77
  78   bool enabled_;
  79
  80   Lock lock_;  // Mutex for state_.
  81   ConditionVariable condition_variable_;
  82   State state_;
  83   const TimeDelta duration_;  // How long after start_time_ do we alarm?
  84   const std::string thread_watched_name_;
  85   PlatformThreadHandle handle_;
  86   ThreadDelegate delegate_;  // Store it, because it must outlive the thread.
  87
  88   TimeTicks start_time_;  // Start of epoch, and alarm after duration_.
  89
  90   DISALLOW_COPY_AND_ASSIGN(Watchdog);
  91 };
  92
  93 }  // namespace base
  94
  95 #endif  // BASE_THREADING_WATCHDOG_H_