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_H_ 6 #define BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_ 7 8 #include "base/base_export.h" 9 #include "base/basictypes.h" 10 11 #if defined(OS_WIN) 12 #include "base/win/scoped_handle.h" 13 #endif 14 15 #if defined(OS_POSIX) 16 #include <list> 17 #include <utility> 18 #include "base/memory/ref_counted.h" 19 #include "base/synchronization/lock.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 BASE_EXPORT 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 // TODO(rvargas): Pass ScopedHandle instead (and on Release). 57 explicit WaitableEvent(HANDLE event_handle); 58 59 // Releases ownership of the handle from this object. 60 HANDLE Release(); 61 #endif 62 63 ~WaitableEvent(); 64 65 // Put the event in the un-signaled state. 66 void Reset(); 67 68 // Put the event in the signaled state. Causing any thread blocked on Wait 69 // to be woken up. 70 void Signal(); 71 72 // Returns true if the event is in the signaled state, else false. If this 73 // is not a manual reset event, then this test will cause a reset. 74 bool IsSignaled(); 75 76 // Wait indefinitely for the event to be signaled. Wait's return "happens 77 // after" |Signal| has completed. This means that it's safe for a 78 // WaitableEvent to synchronise its own destruction, like this: 79 // 80 // WaitableEvent *e = new WaitableEvent; 81 // SendToOtherThread(e); 82 // e->Wait(); 83 // delete e; 84 void Wait(); 85 86 // Wait up until max_time has passed for the event to be signaled. Returns 87 // true if the event was signaled. If this method returns false, then it 88 // does not necessarily mean that max_time was exceeded. 89 // 90 // TimedWait can synchronise its own destruction like |Wait|. 91 bool TimedWait(const TimeDelta& max_time); 92 93 #if defined(OS_WIN) 94 HANDLE handle() const { return handle_.Get(); } 95 #endif 96 97 // Wait, synchronously, on multiple events. 98 // waitables: an array of WaitableEvent pointers 99 // count: the number of elements in @waitables 100 // 101 // returns: the index of a WaitableEvent which has been signaled. 102 // 103 // You MUST NOT delete any of the WaitableEvent objects while this wait is 104 // happening, however WaitMany's return "happens after" the |Signal| call 105 // that caused it has completed, like |Wait|. 106 static size_t WaitMany(WaitableEvent** waitables, size_t count); 107 108 // For asynchronous waiting, see WaitableEventWatcher 109 110 // This is a private helper class. It's here because it's used by friends of 111 // this class (such as WaitableEventWatcher) to be able to enqueue elements 112 // of the wait-list 113 class Waiter { 114 public: 115 // Signal the waiter to wake up. 116 // 117 // Consider the case of a Waiter which is in multiple WaitableEvent's 118 // wait-lists. Each WaitableEvent is automatic-reset and two of them are 119 // signaled at the same time. Now, each will wake only the first waiter in 120 // the wake-list before resetting. However, if those two waiters happen to 121 // be the same object (as can happen if another thread didn't have a chance 122 // to dequeue the waiter from the other wait-list in time), two auto-resets 123 // will have happened, but only one waiter has been signaled! 124 // 125 // Because of this, a Waiter may "reject" a wake by returning false. In 126 // this case, the auto-reset WaitableEvent shouldn't act as if anything has 127 // been notified. 128 virtual bool Fire(WaitableEvent* signaling_event) = 0; 129 130 // Waiters may implement this in order to provide an extra condition for 131 // two Waiters to be considered equal. In WaitableEvent::Dequeue, if the 132 // pointers match then this function is called as a final check. See the 133 // comments in ~Handle for why. 134 virtual bool Compare(void* tag) = 0; 135 136 protected: 137 virtual ~Waiter() {} 138 }; 139 140 private: 141 friend class WaitableEventWatcher; 142 143 #if defined(OS_WIN) 144 win::ScopedHandle handle_; 145 #else 146 // On Windows, one can close a HANDLE which is currently being waited on. The 147 // MSDN documentation says that the resulting behaviour is 'undefined', but 148 // it doesn't crash. However, if we were to include the following members 149 // directly then, on POSIX, one couldn't use WaitableEventWatcher to watch an 150 // event which gets deleted. This mismatch has bitten us several times now, 151 // so we have a kernel of the WaitableEvent, which is reference counted. 152 // WaitableEventWatchers may then take a reference and thus match the Windows 153 // behaviour. 154 struct WaitableEventKernel : 155 public RefCountedThreadSafe<WaitableEventKernel> { 156 public: 157 WaitableEventKernel(bool manual_reset, bool initially_signaled); 158 159 bool Dequeue(Waiter* waiter, void* tag); 160 161 base::Lock lock_; 162 const bool manual_reset_; 163 bool signaled_; 164 std::list<Waiter*> waiters_; 165 166 private: 167 friend class RefCountedThreadSafe<WaitableEventKernel>; 168 ~WaitableEventKernel(); 169 }; 170 171 typedef std::pair<WaitableEvent*, size_t> WaiterAndIndex; 172 173 // When dealing with arrays of WaitableEvent*, we want to sort by the address 174 // of the WaitableEvent in order to have a globally consistent locking order. 175 // In that case we keep them, in sorted order, in an array of pairs where the 176 // second element is the index of the WaitableEvent in the original, 177 // unsorted, array. 178 static size_t EnqueueMany(WaiterAndIndex* waitables, 179 size_t count, Waiter* waiter); 180 181 bool SignalAll(); 182 bool SignalOne(); 183 void Enqueue(Waiter* waiter); 184 185 scoped_refptr<WaitableEventKernel> kernel_; 186 #endif 187 188 DISALLOW_COPY_AND_ASSIGN(WaitableEvent); 189 }; 190 191 } // namespace base 192 193 #endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_ 194
