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