ipc/chromium/src/base/waitable_event.h

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