Fix iOS build for XCode 4.6.
[chromium-blink-merge.git] / base / synchronization / waitable_event_watcher.h
blobf5c1510b8f7ddc8ebcf2e7cbc33e7ca534552145
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.
5 #ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_
6 #define BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_
8 #include "base/base_export.h"
9 #include "build/build_config.h"
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
19 namespace base {
21 class Flag;
22 class AsyncWaiter;
23 class AsyncCallbackTask;
24 class WaitableEvent;
26 // -----------------------------------------------------------------------------
27 // This class provides a way to wait on a WaitableEvent asynchronously.
29 // Each instance of this object can be waiting on a single WaitableEvent. When
30 // the waitable event is signaled, a callback is made in the thread of a given
31 // MessageLoop. This callback can be deleted by deleting the waiter.
33 // Typical usage:
35 // class MyClass : public base::WaitableEventWatcher::Delegate {
36 // public:
37 // void DoStuffWhenSignaled(WaitableEvent *waitable_event) {
38 // watcher_.StartWatching(waitable_event, this);
39 // }
40 // virtual void OnWaitableEventSignaled(WaitableEvent* waitable_event) {
41 // // OK, time to do stuff!
42 // }
43 // private:
44 // base::WaitableEventWatcher watcher_;
45 // };
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.
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.
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 // -----------------------------------------------------------------------------
62 class BASE_EXPORT WaitableEventWatcher
63 #if !defined(OS_WIN)
64 : public MessageLoop::DestructionObserver
65 #endif
67 public:
69 WaitableEventWatcher();
70 virtual ~WaitableEventWatcher();
72 class BASE_EXPORT Delegate {
73 public:
74 // -------------------------------------------------------------------------
75 // This is called on the MessageLoop thread when WaitableEvent has been
76 // signaled.
78 // Note: the event may not be signaled by the time that this function is
79 // called. This indicates only that it has been signaled at some point in
80 // the past.
81 // -------------------------------------------------------------------------
82 virtual void OnWaitableEventSignaled(WaitableEvent* waitable_event) = 0;
84 protected:
85 virtual ~Delegate() { }
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);
95 // ---------------------------------------------------------------------------
96 // Cancel the current watch. Must be called from the same thread which
97 // started the watch.
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();
106 // ---------------------------------------------------------------------------
107 // Return the currently watched event, or NULL if no object is currently being
108 // watched.
109 // ---------------------------------------------------------------------------
110 WaitableEvent* GetWatchedEvent();
112 // ---------------------------------------------------------------------------
113 // Return the delegate, or NULL if there is no delegate.
114 // ---------------------------------------------------------------------------
115 Delegate* delegate() {
116 return delegate_;
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);
131 // -------------------------------------------------------------------------
132 // Implementation of ObjectWatcher::Delegate
133 // -------------------------------------------------------------------------
134 void OnObjectSignaled(HANDLE h);
136 private:
137 WaitableEventWatcher *const watcher_;
140 void OnObjectSignaled();
142 ObjectWatcherHelper helper_;
143 win::ObjectWatcher watcher_;
144 #else
145 // ---------------------------------------------------------------------------
146 // Implementation of MessageLoop::DestructionObserver
147 // ---------------------------------------------------------------------------
148 virtual void WillDestroyCurrentMessageLoop() OVERRIDE;
150 MessageLoop* message_loop_;
151 scoped_refptr<Flag> cancel_flag_;
152 AsyncWaiter* waiter_;
153 base::Closure callback_;
154 scoped_refptr<WaitableEvent::WaitableEventKernel> kernel_;
155 #endif
157 WaitableEvent* event_;
159 Delegate* delegate_;
162 } // namespace base
164 #endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_WATCHER_H_