object_watcher.h 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. // Copyright (c) 2011 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. #ifndef BASE_WIN_OBJECT_WATCHER_H_
  5. #define BASE_WIN_OBJECT_WATCHER_H_
  6. #include "base/win/windows_types.h"
  7. #include "base/base_export.h"
  8. #include "base/callback.h"
  9. #include "base/memory/ref_counted.h"
  10. #include "base/memory/weak_ptr.h"
  11. #include "base/task/sequenced_task_runner.h"
  12. namespace base {
  13. namespace win {
  14. // A class that provides a means to asynchronously wait for a Windows object to
  15. // become signaled. It is an abstraction around RegisterWaitForSingleObject
  16. // that provides a notification callback, OnObjectSignaled, that runs back on
  17. // the origin sequence (i.e., the sequence that called StartWatching).
  18. //
  19. // This class acts like a smart pointer such that when it goes out-of-scope,
  20. // UnregisterWaitEx is automatically called, and any in-flight notification is
  21. // suppressed.
  22. //
  23. // The waiting handle MUST NOT be closed while watching is in progress. If this
  24. // handle is closed while the wait is still pending, the behavior is undefined
  25. // (see MSDN:RegisterWaitForSingleObject).
  26. //
  27. // Typical usage:
  28. //
  29. // class MyClass : public base::win::ObjectWatcher::Delegate {
  30. // public:
  31. // void DoStuffWhenSignaled(HANDLE object) {
  32. // watcher_.StartWatchingOnce(object, this);
  33. // }
  34. // void OnObjectSignaled(HANDLE object) override {
  35. // // OK, time to do stuff!
  36. // }
  37. // private:
  38. // base::win::ObjectWatcher watcher_;
  39. // };
  40. //
  41. // In the above example, MyClass wants to "do stuff" when object becomes
  42. // signaled. ObjectWatcher makes this task easy. When MyClass goes out of
  43. // scope, the watcher_ will be destroyed, and there is no need to worry about
  44. // OnObjectSignaled being called on a deleted MyClass pointer. Easy!
  45. // If the object is already signaled before being watched, OnObjectSignaled is
  46. // still called after (but not necessarily immediately after) watch is started.
  47. //
  48. // NOTE: Except for the constructor, all public methods of this class must be
  49. // called in sequence, in a scope where SequencedTaskRunnerHandle::IsSet().
  50. class BASE_EXPORT ObjectWatcher {
  51. public:
  52. class BASE_EXPORT Delegate {
  53. public:
  54. virtual ~Delegate() = default;
  55. // Called from the sequence that started the watch when a signaled object is
  56. // detected. To continue watching the object, StartWatching must be called
  57. // again.
  58. virtual void OnObjectSignaled(HANDLE object) = 0;
  59. };
  60. ObjectWatcher();
  61. ObjectWatcher(const ObjectWatcher&) = delete;
  62. ObjectWatcher& operator=(const ObjectWatcher&) = delete;
  63. ~ObjectWatcher();
  64. // When the object is signaled, the given delegate is notified on the sequence
  65. // where StartWatchingOnce is called. The ObjectWatcher is not responsible for
  66. // deleting the delegate.
  67. // Returns whether watching was successfully initiated.
  68. bool StartWatchingOnce(HANDLE object,
  69. Delegate* delegate,
  70. const Location& from_here = Location::Current());
  71. // Notifies the delegate, on the sequence where this method is called, each
  72. // time the object is set. By definition, the handle must be an auto-reset
  73. // object. The caller must ensure that it (or any Windows system code) doesn't
  74. // reset the event or else the delegate won't be called.
  75. // Returns whether watching was successfully initiated.
  76. bool StartWatchingMultipleTimes(
  77. HANDLE object,
  78. Delegate* delegate,
  79. const Location& from_here = Location::Current());
  80. // Stops watching. Does nothing if the watch has already completed. If the
  81. // watch is still active, then it is canceled, and the associated delegate is
  82. // not notified.
  83. //
  84. // Returns true if the watch was canceled. Otherwise, false is returned.
  85. bool StopWatching();
  86. // Returns true if currently watching an object.
  87. bool IsWatching() const;
  88. // Returns the handle of the object being watched.
  89. HANDLE GetWatchedObject() const;
  90. private:
  91. // Called on a background thread when done waiting.
  92. static void CALLBACK DoneWaiting(void* param, BOOLEAN timed_out);
  93. // Helper used by StartWatchingOnce and StartWatchingMultipleTimes.
  94. bool StartWatchingInternal(HANDLE object,
  95. Delegate* delegate,
  96. bool execute_only_once,
  97. const Location& from_here);
  98. void Signal(Delegate* delegate);
  99. void Reset();
  100. Location location_;
  101. // A callback pre-bound to Signal() that is posted to the caller's task runner
  102. // when the wait completes.
  103. RepeatingClosure callback_;
  104. // The object being watched.
  105. HANDLE object_ = nullptr;
  106. // The wait handle returned by RegisterWaitForSingleObject.
  107. HANDLE wait_object_ = nullptr;
  108. // The task runner of the sequence on which the watch was started.
  109. scoped_refptr<SequencedTaskRunner> task_runner_;
  110. bool run_once_ = true;
  111. WeakPtrFactory<ObjectWatcher> weak_factory_{this};
  112. };
  113. } // namespace win
  114. } // namespace base
  115. #endif // BASE_WIN_OBJECT_WATCHER_H_