waitable_event.h - mozsearch

Enable keyboard shortcuts

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */

/* vim: set ts=8 sts=2 et sw=2 tw=80: */

// 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(XP_WIN)

#  include <windows.h>

#endif

#if defined(XP_UNIX)

#  include <list>

#  include <utility>

#  include "base/condition_variable.h"

#  include "base/lock.h"

#  include "nsISupportsImpl.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);

  ~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(XP_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(XP_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 final {

   public:

    NS_INLINE_DECL_THREADSAFE_REFCOUNTING(WaitableEventKernel)

    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_;

   protected:

    ~WaitableEventKernel() {}

};

  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_