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