The Tor Browser: ipc/chromium/src/base/waitable_event.h@6474c204b198 (annotated)

ipc/chromium/src/base/waitable_event.h@6474c204b198 (annotated)

ipc/chromium/src/base/waitable_event.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

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

The Tor Browser / annotate

ipc/chromium/src/base/waitable_event.h@6474c204b198 (annotated)

ipc/chromium/src/base/waitable_event.h