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/macros.h"
26 #include "base/synchronization/condition_variable.h"
27 #include "base/synchronization/lock.h"
28 #include "base/threading/platform_thread.h"
29 #include "base/time/time.h"
30 
31 namespace base {
32 
33 class BASE_EXPORT Watchdog {
34  public:
35   // Constructor specifies how long the Watchdog will wait before alarming.
36   Watchdog(const TimeDelta& duration,
37            const std::string& thread_watched_name,
38            bool enabled);
39   virtual ~Watchdog();
40 
41   // Notify watchdog thread to finish up. Sets the state_ to SHUTDOWN.
42   void Cleanup();
43 
44   // Returns true if we state_ is JOINABLE (which indicates that Watchdog has
45   // exited).
46   bool IsJoinable();
47 
48   // Start timing, and alarm when time expires (unless we're disarm()ed.)
49   void Arm();  // Arm  starting now.
50   void ArmSomeTimeDeltaAgo(const TimeDelta& time_delta);
51   void ArmAtStartTime(const TimeTicks start_time);
52 
53   // Reset time, and do not set off the alarm.
54   void Disarm();
55 
56   // Alarm is called if the time expires after an Arm() without someone calling
57   // Disarm().  This method can be overridden to create testable classes.
58   virtual void Alarm();
59 
60   // Reset static data to initial state. Useful for tests, to ensure
61   // they are independent.
62   static void ResetStaticData();
63 
64  private:
65   class ThreadDelegate : public PlatformThread::Delegate {
66    public:
ThreadDelegate(Watchdog * watchdog)67     explicit ThreadDelegate(Watchdog* watchdog) : watchdog_(watchdog) {
68     }
69     void ThreadMain() override;
70 
71    private:
72     void SetThreadName() const;
73 
74     Watchdog* watchdog_;
75   };
76 
77   enum State {ARMED, DISARMED, SHUTDOWN, JOINABLE };
78 
79   bool enabled_;
80 
81   Lock lock_;  // Mutex for state_.
82   ConditionVariable condition_variable_;
83   State state_;
84   const TimeDelta duration_;  // How long after start_time_ do we alarm?
85   const std::string thread_watched_name_;
86   PlatformThreadHandle handle_;
87   ThreadDelegate delegate_;  // Store it, because it must outlive the thread.
88 
89   TimeTicks start_time_;  // Start of epoch, and alarm after duration_.
90 
91   DISALLOW_COPY_AND_ASSIGN(Watchdog);
92 };
93 
94 }  // namespace base
95 
96 #endif  // BASE_THREADING_WATCHDOG_H_
97