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 #ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 6 #define BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 7 8 #include "base/base_export.h" 9 #include "build/build_config.h" 10 11 #if defined(OS_WIN) 12 #include "base/win/object_watcher.h" 13 #else 14 #include "base/callback.h" 15 #include "base/message_loop/message_loop.h" 16 #include "base/synchronization/waitable_event.h" 17 #endif 18 19 namespace base { 20 21 class Flag; 22 class AsyncWaiter; 23 class AsyncCallbackTask; 24 class WaitableEvent; 25 26 // This class provides a way to wait on a WaitableEvent asynchronously. 27 // 28 // Each instance of this object can be waiting on a single WaitableEvent. When 29 // the waitable event is signaled, a callback is made in the thread of a given 30 // MessageLoop. This callback can be deleted by deleting the waiter. 31 // 32 // Typical usage: 33 // 34 // class MyClass { 35 // public: 36 // void DoStuffWhenSignaled(WaitableEvent *waitable_event) { 37 // watcher_.StartWatching(waitable_event, 38 // base::Bind(&MyClass::OnWaitableEventSignaled, this); 39 // } 40 // private: 41 // void OnWaitableEventSignaled(WaitableEvent* waitable_event) { 42 // // OK, time to do stuff! 43 // } 44 // base::WaitableEventWatcher watcher_; 45 // }; 46 // 47 // In the above example, MyClass wants to "do stuff" when waitable_event 48 // becomes signaled. WaitableEventWatcher makes this task easy. When MyClass 49 // goes out of scope, the watcher_ will be destroyed, and there is no need to 50 // worry about OnWaitableEventSignaled being called on a deleted MyClass 51 // pointer. 52 // 53 // BEWARE: With automatically reset WaitableEvents, a signal may be lost if it 54 // occurs just before a WaitableEventWatcher is deleted. There is currently no 55 // safe way to stop watching an automatic reset WaitableEvent without possibly 56 // missing a signal. 57 // 58 // NOTE: you /are/ allowed to delete the WaitableEvent while still waiting on 59 // it with a Watcher. It will act as if the event was never signaled. 60 61 class BASE_EXPORT WaitableEventWatcher 62 #if defined(OS_WIN) 63 : public win::ObjectWatcher::Delegate { 64 #else 65 : public MessageLoop::DestructionObserver { 66 #endif 67 public: 68 typedef Callback<void(WaitableEvent*)> EventCallback; 69 WaitableEventWatcher(); 70 ~WaitableEventWatcher() override; 71 72 // When @event is signaled, the given callback is called on the thread of the 73 // current message loop when StartWatching is called. 74 bool StartWatching(WaitableEvent* event, const EventCallback& callback); 75 76 // Cancel the current watch. Must be called from the same thread which 77 // started the watch. 78 // 79 // Does nothing if no event is being watched, nor if the watch has completed. 80 // The callback will *not* be called for the current watch after this 81 // function returns. Since the callback runs on the same thread as this 82 // function, it cannot be called during this function either. 83 void StopWatching(); 84 85 // Return the currently watched event, or NULL if no object is currently being 86 // watched. 87 WaitableEvent* GetWatchedEvent(); 88 89 // Return the callback that will be invoked when the event is 90 // signaled. callback()91 const EventCallback& callback() const { return callback_; } 92 93 private: 94 #if defined(OS_WIN) 95 void OnObjectSignaled(HANDLE h) override; 96 win::ObjectWatcher watcher_; 97 #else 98 // Implementation of MessageLoop::DestructionObserver 99 void WillDestroyCurrentMessageLoop() override; 100 101 MessageLoop* message_loop_; 102 scoped_refptr<Flag> cancel_flag_; 103 AsyncWaiter* waiter_; 104 base::Closure internal_callback_; 105 scoped_refptr<WaitableEvent::WaitableEventKernel> kernel_; 106 #endif 107 108 WaitableEvent* event_; 109 EventCallback callback_; 110 }; 111 112 } // namespace base 113 114 #endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 115