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
30namespace base {
31
32class 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    virtual void ThreadMain() OVERRIDE;
69   private:
70    void SetThreadName() const;
71
72    Watchdog* watchdog_;
73  };
74
75  enum State {ARMED, DISARMED, SHUTDOWN, JOINABLE };
76
77  bool enabled_;
78
79  Lock lock_;  // Mutex for state_.
80  ConditionVariable condition_variable_;
81  State state_;
82  const TimeDelta duration_;  // How long after start_time_ do we alarm?
83  const std::string thread_watched_name_;
84  PlatformThreadHandle handle_;
85  ThreadDelegate delegate_;  // Store it, because it must outlive the thread.
86
87  TimeTicks start_time_;  // Start of epoch, and alarm after duration_.
88
89  DISALLOW_COPY_AND_ASSIGN(Watchdog);
90};
91
92}  // namespace base
93
94#endif  // BASE_THREADING_WATCHDOG_H_
95