michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved. michael@0: // Use of this source code is governed by a BSD-style license that can be michael@0: // found in the LICENSE file. michael@0: michael@0: #ifndef BASE_WAITABLE_EVENT_H_ michael@0: #define BASE_WAITABLE_EVENT_H_ michael@0: michael@0: #include "base/basictypes.h" michael@0: michael@0: #if defined(OS_WIN) michael@0: #include michael@0: #endif michael@0: michael@0: #if defined(OS_POSIX) michael@0: #include michael@0: #include michael@0: #include "base/condition_variable.h" michael@0: #include "base/lock.h" michael@0: #include "base/ref_counted.h" michael@0: #endif michael@0: michael@0: #include "base/message_loop.h" michael@0: michael@0: namespace base { michael@0: michael@0: // This replaces INFINITE from Win32 michael@0: static const int kNoTimeout = -1; michael@0: michael@0: class TimeDelta; michael@0: michael@0: // A WaitableEvent can be a useful thread synchronization tool when you want to michael@0: // allow one thread to wait for another thread to finish some work. For michael@0: // non-Windows systems, this can only be used from within a single address michael@0: // space. michael@0: // michael@0: // Use a WaitableEvent when you would otherwise use a Lock+ConditionVariable to michael@0: // protect a simple boolean value. However, if you find yourself using a michael@0: // WaitableEvent in conjunction with a Lock to wait for a more complex state michael@0: // change (e.g., for an item to be added to a queue), then you should probably michael@0: // be using a ConditionVariable instead of a WaitableEvent. michael@0: // michael@0: // NOTE: On Windows, this class provides a subset of the functionality afforded michael@0: // by a Windows event object. This is intentional. If you are writing Windows michael@0: // specific code and you need other features of a Windows event, then you might michael@0: // be better off just using an Windows event directly. michael@0: class WaitableEvent { michael@0: public: michael@0: // If manual_reset is true, then to set the event state to non-signaled, a michael@0: // consumer must call the Reset method. If this parameter is false, then the michael@0: // system automatically resets the event state to non-signaled after a single michael@0: // waiting thread has been released. michael@0: WaitableEvent(bool manual_reset, bool initially_signaled); michael@0: michael@0: #if defined(OS_WIN) michael@0: // Create a WaitableEvent from an Event HANDLE which has already been michael@0: // created. This objects takes ownership of the HANDLE and will close it when michael@0: // deleted. michael@0: explicit WaitableEvent(HANDLE event_handle); michael@0: michael@0: // Releases ownership of the handle from this object. michael@0: HANDLE Release(); michael@0: #endif michael@0: michael@0: ~WaitableEvent(); michael@0: michael@0: // Put the event in the un-signaled state. michael@0: void Reset(); michael@0: michael@0: // Put the event in the signaled state. Causing any thread blocked on Wait michael@0: // to be woken up. michael@0: void Signal(); michael@0: michael@0: // Returns true if the event is in the signaled state, else false. If this michael@0: // is not a manual reset event, then this test will cause a reset. michael@0: bool IsSignaled(); michael@0: michael@0: // Wait indefinitely for the event to be signaled. Returns true if the event michael@0: // was signaled, else false is returned to indicate that waiting failed. michael@0: bool Wait(); michael@0: michael@0: // Wait up until max_time has passed for the event to be signaled. Returns michael@0: // true if the event was signaled. If this method returns false, then it michael@0: // does not necessarily mean that max_time was exceeded. michael@0: bool TimedWait(const TimeDelta& max_time); michael@0: michael@0: #if defined(OS_WIN) michael@0: HANDLE handle() const { return handle_; } michael@0: #endif michael@0: michael@0: // Wait, synchronously, on multiple events. michael@0: // waitables: an array of WaitableEvent pointers michael@0: // count: the number of elements in @waitables michael@0: // michael@0: // returns: the index of a WaitableEvent which has been signaled. michael@0: // michael@0: // You MUST NOT delete any of the WaitableEvent objects while this wait is michael@0: // happening. michael@0: static size_t WaitMany(WaitableEvent** waitables, size_t count); michael@0: michael@0: // For asynchronous waiting, see WaitableEventWatcher michael@0: michael@0: // This is a private helper class. It's here because it's used by friends of michael@0: // this class (such as WaitableEventWatcher) to be able to enqueue elements michael@0: // of the wait-list michael@0: class Waiter { michael@0: public: michael@0: // Signal the waiter to wake up. michael@0: // michael@0: // Consider the case of a Waiter which is in multiple WaitableEvent's michael@0: // wait-lists. Each WaitableEvent is automatic-reset and two of them are michael@0: // signaled at the same time. Now, each will wake only the first waiter in michael@0: // the wake-list before resetting. However, if those two waiters happen to michael@0: // be the same object (as can happen if another thread didn't have a chance michael@0: // to dequeue the waiter from the other wait-list in time), two auto-resets michael@0: // will have happened, but only one waiter has been signaled! michael@0: // michael@0: // Because of this, a Waiter may "reject" a wake by returning false. In michael@0: // this case, the auto-reset WaitableEvent shouldn't act as if anything has michael@0: // been notified. michael@0: virtual bool Fire(WaitableEvent* signaling_event) = 0; michael@0: michael@0: // Waiters may implement this in order to provide an extra condition for michael@0: // two Waiters to be considered equal. In WaitableEvent::Dequeue, if the michael@0: // pointers match then this function is called as a final check. See the michael@0: // comments in ~Handle for why. michael@0: virtual bool Compare(void* tag) = 0; michael@0: }; michael@0: michael@0: private: michael@0: friend class WaitableEventWatcher; michael@0: michael@0: #if defined(OS_WIN) michael@0: HANDLE handle_; michael@0: #else michael@0: // On Windows, one can close a HANDLE which is currently being waited on. The michael@0: // MSDN documentation says that the resulting behaviour is 'undefined', but michael@0: // it doesn't crash. However, if we were to include the following members michael@0: // directly then, on POSIX, one couldn't use WaitableEventWatcher to watch an michael@0: // event which gets deleted. This mismatch has bitten us several times now, michael@0: // so we have a kernel of the WaitableEvent, which is reference counted. michael@0: // WaitableEventWatchers may then take a reference and thus match the Windows michael@0: // behaviour. michael@0: struct WaitableEventKernel : michael@0: public RefCountedThreadSafe { michael@0: public: michael@0: WaitableEventKernel(bool manual_reset, bool initially_signaled) michael@0: : manual_reset_(manual_reset), michael@0: signaled_(initially_signaled) { michael@0: } michael@0: michael@0: bool Dequeue(Waiter* waiter, void* tag); michael@0: michael@0: Lock lock_; michael@0: const bool manual_reset_; michael@0: bool signaled_; michael@0: std::list waiters_; michael@0: }; michael@0: michael@0: scoped_refptr kernel_; michael@0: michael@0: bool SignalAll(); michael@0: bool SignalOne(); michael@0: void Enqueue(Waiter* waiter); michael@0: michael@0: // When dealing with arrays of WaitableEvent*, we want to sort by the address michael@0: // of the WaitableEvent in order to have a globally consistent locking order. michael@0: // In that case we keep them, in sorted order, in an array of pairs where the michael@0: // second element is the index of the WaitableEvent in the original, michael@0: // unsorted, array. michael@0: typedef std::pair WaiterAndIndex; michael@0: static size_t EnqueueMany(WaiterAndIndex* waitables, michael@0: size_t count, Waiter* waiter); michael@0: #endif michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(WaitableEvent); michael@0: }; michael@0: michael@0: } // namespace base michael@0: michael@0: #endif // BASE_WAITABLE_EVENT_H_