OLD | NEW |
| (Empty) |
1 // Copyright (c) 2009 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_H_ | |
6 #define BASE_WAITABLE_EVENT_H_ | |
7 #pragma once | |
8 | |
9 #include "base/basictypes.h" | |
10 | |
11 #if defined(OS_WIN) | |
12 #include <windows.h> | |
13 #endif | |
14 | |
15 #if defined(OS_POSIX) | |
16 #include <list> | |
17 #include <utility> | |
18 #include "base/lock.h" | |
19 #include "base/ref_counted.h" | |
20 #endif | |
21 | |
22 namespace base { | |
23 | |
24 // This replaces INFINITE from Win32 | |
25 static const int kNoTimeout = -1; | |
26 | |
27 class TimeDelta; | |
28 | |
29 // A WaitableEvent can be a useful thread synchronization tool when you want to | |
30 // allow one thread to wait for another thread to finish some work. For | |
31 // non-Windows systems, this can only be used from within a single address | |
32 // space. | |
33 // | |
34 // Use a WaitableEvent when you would otherwise use a Lock+ConditionVariable to | |
35 // protect a simple boolean value. However, if you find yourself using a | |
36 // WaitableEvent in conjunction with a Lock to wait for a more complex state | |
37 // change (e.g., for an item to be added to a queue), then you should probably | |
38 // be using a ConditionVariable instead of a WaitableEvent. | |
39 // | |
40 // NOTE: On Windows, this class provides a subset of the functionality afforded | |
41 // by a Windows event object. This is intentional. If you are writing Windows | |
42 // specific code and you need other features of a Windows event, then you might | |
43 // be better off just using an Windows event directly. | |
44 class WaitableEvent { | |
45 public: | |
46 // If manual_reset is true, then to set the event state to non-signaled, a | |
47 // consumer must call the Reset method. If this parameter is false, then the | |
48 // system automatically resets the event state to non-signaled after a single | |
49 // waiting thread has been released. | |
50 WaitableEvent(bool manual_reset, bool initially_signaled); | |
51 | |
52 #if defined(OS_WIN) | |
53 // Create a WaitableEvent from an Event HANDLE which has already been | |
54 // created. This objects takes ownership of the HANDLE and will close it when | |
55 // deleted. | |
56 explicit WaitableEvent(HANDLE event_handle); | |
57 | |
58 // Releases ownership of the handle from this object. | |
59 HANDLE Release(); | |
60 #endif | |
61 | |
62 ~WaitableEvent(); | |
63 | |
64 // Put the event in the un-signaled state. | |
65 void Reset(); | |
66 | |
67 // Put the event in the signaled state. Causing any thread blocked on Wait | |
68 // to be woken up. | |
69 void Signal(); | |
70 | |
71 // Returns true if the event is in the signaled state, else false. If this | |
72 // is not a manual reset event, then this test will cause a reset. | |
73 bool IsSignaled(); | |
74 | |
75 // Wait indefinitely for the event to be signaled. Returns true if the event | |
76 // was signaled, else false is returned to indicate that waiting failed. | |
77 bool Wait(); | |
78 | |
79 // Wait up until max_time has passed for the event to be signaled. Returns | |
80 // true if the event was signaled. If this method returns false, then it | |
81 // does not necessarily mean that max_time was exceeded. | |
82 bool TimedWait(const TimeDelta& max_time); | |
83 | |
84 #if defined(OS_WIN) | |
85 HANDLE handle() const { return handle_; } | |
86 #endif | |
87 | |
88 // Wait, synchronously, on multiple events. | |
89 // waitables: an array of WaitableEvent pointers | |
90 // count: the number of elements in @waitables | |
91 // | |
92 // returns: the index of a WaitableEvent which has been signaled. | |
93 // | |
94 // You MUST NOT delete any of the WaitableEvent objects while this wait is | |
95 // happening. | |
96 static size_t WaitMany(WaitableEvent** waitables, size_t count); | |
97 | |
98 // For asynchronous waiting, see WaitableEventWatcher | |
99 | |
100 // This is a private helper class. It's here because it's used by friends of | |
101 // this class (such as WaitableEventWatcher) to be able to enqueue elements | |
102 // of the wait-list | |
103 class Waiter { | |
104 public: | |
105 // Signal the waiter to wake up. | |
106 // | |
107 // Consider the case of a Waiter which is in multiple WaitableEvent's | |
108 // wait-lists. Each WaitableEvent is automatic-reset and two of them are | |
109 // signaled at the same time. Now, each will wake only the first waiter in | |
110 // the wake-list before resetting. However, if those two waiters happen to | |
111 // be the same object (as can happen if another thread didn't have a chance | |
112 // to dequeue the waiter from the other wait-list in time), two auto-resets | |
113 // will have happened, but only one waiter has been signaled! | |
114 // | |
115 // Because of this, a Waiter may "reject" a wake by returning false. In | |
116 // this case, the auto-reset WaitableEvent shouldn't act as if anything has | |
117 // been notified. | |
118 virtual bool Fire(WaitableEvent* signaling_event) = 0; | |
119 | |
120 // Waiters may implement this in order to provide an extra condition for | |
121 // two Waiters to be considered equal. In WaitableEvent::Dequeue, if the | |
122 // pointers match then this function is called as a final check. See the | |
123 // comments in ~Handle for why. | |
124 virtual bool Compare(void* tag) = 0; | |
125 | |
126 protected: | |
127 virtual ~Waiter() {} | |
128 }; | |
129 | |
130 private: | |
131 friend class WaitableEventWatcher; | |
132 | |
133 #if defined(OS_WIN) | |
134 HANDLE handle_; | |
135 #else | |
136 // On Windows, one can close a HANDLE which is currently being waited on. The | |
137 // MSDN documentation says that the resulting behaviour is 'undefined', but | |
138 // it doesn't crash. However, if we were to include the following members | |
139 // directly then, on POSIX, one couldn't use WaitableEventWatcher to watch an | |
140 // event which gets deleted. This mismatch has bitten us several times now, | |
141 // so we have a kernel of the WaitableEvent, which is reference counted. | |
142 // WaitableEventWatchers may then take a reference and thus match the Windows | |
143 // behaviour. | |
144 struct WaitableEventKernel : | |
145 public RefCountedThreadSafe<WaitableEventKernel> { | |
146 public: | |
147 WaitableEventKernel(bool manual_reset, bool initially_signaled); | |
148 virtual ~WaitableEventKernel(); | |
149 | |
150 bool Dequeue(Waiter* waiter, void* tag); | |
151 | |
152 Lock lock_; | |
153 const bool manual_reset_; | |
154 bool signaled_; | |
155 std::list<Waiter*> waiters_; | |
156 }; | |
157 | |
158 scoped_refptr<WaitableEventKernel> kernel_; | |
159 | |
160 bool SignalAll(); | |
161 bool SignalOne(); | |
162 void Enqueue(Waiter* waiter); | |
163 | |
164 // When dealing with arrays of WaitableEvent*, we want to sort by the address | |
165 // of the WaitableEvent in order to have a globally consistent locking order. | |
166 // In that case we keep them, in sorted order, in an array of pairs where the | |
167 // second element is the index of the WaitableEvent in the original, | |
168 // unsorted, array. | |
169 typedef std::pair<WaitableEvent*, size_t> WaiterAndIndex; | |
170 static size_t EnqueueMany(WaiterAndIndex* waitables, | |
171 size_t count, Waiter* waiter); | |
172 #endif | |
173 | |
174 DISALLOW_COPY_AND_ASSIGN(WaitableEvent); | |
175 }; | |
176 | |
177 } // namespace base | |
178 | |
179 #endif // BASE_WAITABLE_EVENT_H_ | |
OLD | NEW |