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 5#ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 6#define BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 7#pragma once 8 9#include "build/build_config.h" 10 11#if defined(OS_WIN) 12#include "base/win/object_watcher.h" 13#else 14#include "base/message_loop.h" 15#include "base/synchronization/waitable_event.h" 16#endif 17 18#include "base/base_api.h" 19 20namespace base { 21 22class Flag; 23class AsyncWaiter; 24class AsyncCallbackTask; 25class WaitableEvent; 26 27// ----------------------------------------------------------------------------- 28// This class provides a way to wait on a WaitableEvent asynchronously. 29// 30// Each instance of this object can be waiting on a single WaitableEvent. When 31// the waitable event is signaled, a callback is made in the thread of a given 32// MessageLoop. This callback can be deleted by deleting the waiter. 33// 34// Typical usage: 35// 36// class MyClass : public base::WaitableEventWatcher::Delegate { 37// public: 38// void DoStuffWhenSignaled(WaitableEvent *waitable_event) { 39// watcher_.StartWatching(waitable_event, this); 40// } 41// virtual void OnWaitableEventSignaled(WaitableEvent* waitable_event) { 42// // OK, time to do stuff! 43// } 44// private: 45// base::WaitableEventWatcher watcher_; 46// }; 47// 48// In the above example, MyClass wants to "do stuff" when waitable_event 49// becomes signaled. WaitableEventWatcher makes this task easy. When MyClass 50// goes out of scope, the watcher_ will be destroyed, and there is no need to 51// worry about OnWaitableEventSignaled being called on a deleted MyClass 52// pointer. 53// 54// BEWARE: With automatically reset WaitableEvents, a signal may be lost if it 55// occurs just before a WaitableEventWatcher is deleted. There is currently no 56// safe way to stop watching an automatic reset WaitableEvent without possibly 57// missing a signal. 58// 59// NOTE: you /are/ allowed to delete the WaitableEvent while still waiting on 60// it with a Watcher. It will act as if the event was never signaled. 61// ----------------------------------------------------------------------------- 62 63class BASE_API WaitableEventWatcher 64#if defined(OS_POSIX) 65 : public MessageLoop::DestructionObserver 66#endif 67{ 68 public: 69 70 WaitableEventWatcher(); 71 ~WaitableEventWatcher(); 72 73 class Delegate { 74 public: 75 virtual ~Delegate() { } 76 77 // ------------------------------------------------------------------------- 78 // This is called on the MessageLoop thread when WaitableEvent has been 79 // signaled. 80 // 81 // Note: the event may not be signaled by the time that this function is 82 // called. This indicates only that it has been signaled at some point in 83 // the past. 84 // ------------------------------------------------------------------------- 85 virtual void OnWaitableEventSignaled(WaitableEvent* waitable_event) = 0; 86 }; 87 88 // --------------------------------------------------------------------------- 89 // When @event is signaled, the given delegate is called on the thread of the 90 // current message loop when StartWatching is called. The delegate is not 91 // deleted. 92 // --------------------------------------------------------------------------- 93 bool StartWatching(WaitableEvent* event, Delegate* delegate); 94 95 // --------------------------------------------------------------------------- 96 // Cancel the current watch. Must be called from the same thread which 97 // started the watch. 98 // 99 // Does nothing if no event is being watched, nor if the watch has completed. 100 // The delegate will *not* be called for the current watch after this 101 // function returns. Since the delegate runs on the same thread as this 102 // function, it cannot be called during this function either. 103 // --------------------------------------------------------------------------- 104 void StopWatching(); 105 106 // --------------------------------------------------------------------------- 107 // Return the currently watched event, or NULL if no object is currently being 108 // watched. 109 // --------------------------------------------------------------------------- 110 WaitableEvent* GetWatchedEvent(); 111 112 // --------------------------------------------------------------------------- 113 // Return the delegate, or NULL if there is no delegate. 114 // --------------------------------------------------------------------------- 115 Delegate* delegate() { 116 return delegate_; 117 } 118 119 private: 120#if defined(OS_WIN) 121 // --------------------------------------------------------------------------- 122 // The helper class exists because, if WaitableEventWatcher were to inherit 123 // from ObjectWatcher::Delegate, then it couldn't also have an inner class 124 // called Delegate (at least on Windows). Thus this object exists to proxy 125 // the callback function 126 // --------------------------------------------------------------------------- 127 class ObjectWatcherHelper : public win::ObjectWatcher::Delegate { 128 public: 129 ObjectWatcherHelper(WaitableEventWatcher* watcher); 130 131 // ------------------------------------------------------------------------- 132 // Implementation of ObjectWatcher::Delegate 133 // ------------------------------------------------------------------------- 134 void OnObjectSignaled(HANDLE h); 135 136 private: 137 WaitableEventWatcher *const watcher_; 138 }; 139 140 void OnObjectSignaled(); 141 142 ObjectWatcherHelper helper_; 143 win::ObjectWatcher watcher_; 144#else 145 // --------------------------------------------------------------------------- 146 // Implementation of MessageLoop::DestructionObserver 147 // --------------------------------------------------------------------------- 148 virtual void WillDestroyCurrentMessageLoop(); 149 150 MessageLoop* message_loop_; 151 scoped_refptr<Flag> cancel_flag_; 152 AsyncWaiter* waiter_; 153 AsyncCallbackTask* callback_task_; 154 scoped_refptr<WaitableEvent::WaitableEventKernel> kernel_; 155#endif 156 157 WaitableEvent* event_; 158 159 Delegate* delegate_; 160}; 161 162} // namespace base 163 164#endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_ 165