1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 6 #define BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 7 8 #include "base/base_export.h" 9 #include "base/memory/raw_ptr.h" 10 #include "base/task/sequenced_task_runner.h" 11 #include "build/build_config.h" 12 13 #if BUILDFLAG(IS_WIN) 14 #include "base/win/object_watcher.h" 15 #include "base/win/scoped_handle.h" 16 #elif BUILDFLAG(IS_APPLE) 17 #include <dispatch/dispatch.h> 18 19 #include <memory> 20 21 #include "base/memory/weak_ptr.h" 22 #include "base/synchronization/waitable_event.h" 23 #else 24 #include "base/sequence_checker.h" 25 #include "base/synchronization/waitable_event.h" 26 #endif 27 28 #if !BUILDFLAG(IS_WIN) 29 #include "base/functional/callback.h" 30 #endif 31 32 namespace base { 33 34 class Flag; 35 class AsyncWaiter; 36 class WaitableEvent; 37 38 // This class provides a way to wait on a WaitableEvent asynchronously. 39 // 40 // Each instance of this object can be waiting on a single WaitableEvent. When 41 // the waitable event is signaled, a callback is invoked on the sequence that 42 // called StartWatching(). This callback can be deleted by deleting the waiter. 43 // 44 // Typical usage: 45 // 46 // class MyClass { 47 // public: 48 // void DoStuffWhenSignaled(WaitableEvent *waitable_event) { 49 // watcher_.StartWatching(waitable_event, 50 // base::BindOnce(&MyClass::OnWaitableEventSignaled, this); 51 // } 52 // private: 53 // void OnWaitableEventSignaled(WaitableEvent* waitable_event) { 54 // // OK, time to do stuff! 55 // } 56 // base::WaitableEventWatcher watcher_; 57 // }; 58 // 59 // In the above example, MyClass wants to "do stuff" when waitable_event 60 // becomes signaled. WaitableEventWatcher makes this task easy. When MyClass 61 // goes out of scope, the watcher_ will be destroyed, and there is no need to 62 // worry about OnWaitableEventSignaled being called on a deleted MyClass 63 // pointer. 64 // 65 // BEWARE: With automatically reset WaitableEvents, a signal may be lost if it 66 // occurs just before a WaitableEventWatcher is deleted. There is currently no 67 // safe way to stop watching an automatic reset WaitableEvent without possibly 68 // missing a signal. 69 // 70 // NOTE: you /are/ allowed to delete the WaitableEvent while still waiting on 71 // it with a Watcher. But pay attention: if the event was signaled and deleted 72 // right after, the callback may be called with deleted WaitableEvent pointer. 73 74 class BASE_EXPORT WaitableEventWatcher 75 #if BUILDFLAG(IS_WIN) 76 : public win::ObjectWatcher::Delegate 77 #endif 78 { 79 public: 80 using EventCallback = OnceCallback<void(WaitableEvent*)>; 81 82 WaitableEventWatcher(); 83 84 WaitableEventWatcher(const WaitableEventWatcher&) = delete; 85 WaitableEventWatcher& operator=(const WaitableEventWatcher&) = delete; 86 87 #if BUILDFLAG(IS_WIN) 88 ~WaitableEventWatcher() override; 89 #else 90 ~WaitableEventWatcher(); 91 #endif 92 93 // When |event| is signaled, |callback| is called on the sequence that called 94 // StartWatching(). 95 // |task_runner| is used for asynchronous executions of calling |callback|. 96 bool StartWatching(WaitableEvent* event, 97 EventCallback callback, 98 scoped_refptr<SequencedTaskRunner> task_runner); 99 100 // Cancel the current watch. Must be called from the same sequence which 101 // started the watch. 102 // 103 // Does nothing if no event is being watched, nor if the watch has completed. 104 // The callback will *not* be called for the current watch after this 105 // function returns. Since the callback runs on the same sequence as this 106 // function, it cannot be called during this function either. 107 void StopWatching(); 108 109 private: 110 #if BUILDFLAG(IS_WIN) 111 void OnObjectSignaled(HANDLE h) override; 112 113 // Duplicated handle of the event passed to StartWatching(). 114 win::ScopedHandle duplicated_event_handle_; 115 116 // A watcher for |duplicated_event_handle_|. The handle MUST outlive 117 // |watcher_|. 118 win::ObjectWatcher watcher_; 119 120 EventCallback callback_; 121 raw_ptr<WaitableEvent, AcrossTasksDanglingUntriaged> event_ = nullptr; 122 #elif BUILDFLAG(IS_APPLE) 123 // Invokes the callback and resets the source. Must be called on the task 124 // runner on which StartWatching() was called. 125 void InvokeCallback(); 126 127 // Closure bound to the event being watched. This will be is_null() if 128 // nothing is being watched. 129 OnceClosure callback_; 130 131 // A reference to the receive right that is kept alive while a watcher 132 // is waiting. Null if no event is being watched. 133 scoped_refptr<WaitableEvent::ReceiveRight> receive_right_; 134 135 struct Storage; 136 std::unique_ptr<Storage> storage_; 137 138 // Used to vend a weak pointer for calling InvokeCallback() from the 139 // |source_| event handler. 140 WeakPtrFactory<WaitableEventWatcher> weak_ptr_factory_; 141 #else 142 // Instantiated in StartWatching(). Set before the callback runs. Reset in 143 // StopWatching() or StartWatching(). 144 scoped_refptr<Flag> cancel_flag_; 145 146 // Enqueued in the wait list of the watched WaitableEvent. 147 raw_ptr<AsyncWaiter, AcrossTasksDanglingUntriaged> waiter_ = nullptr; 148 149 // Kernel of the watched WaitableEvent. 150 scoped_refptr<WaitableEvent::WaitableEventKernel> kernel_; 151 152 // Ensures that StartWatching() and StopWatching() are called on the same 153 // sequence. 154 SEQUENCE_CHECKER(sequence_checker_); 155 #endif 156 }; 157 158 } // namespace base 159 160 #endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 161