waitable_event_watcher.h revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd
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.h" 16#include "base/synchronization/waitable_event.h" 17#endif 18 19namespace base { 20 21class Flag; 22class AsyncWaiter; 23class AsyncCallbackTask; 24class 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 61class 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 virtual ~WaitableEventWatcher(); 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. 91 const EventCallback& callback() const { return callback_; } 92 93 private: 94#if defined(OS_WIN) 95 virtual void OnObjectSignaled(HANDLE h) OVERRIDE; 96 win::ObjectWatcher watcher_; 97#else 98 // Implementation of MessageLoop::DestructionObserver 99 virtual 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