base/synchronization/condition_variable.h

   1 // Copyright (c) 2011 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 // ConditionVariable wraps pthreads condition variable synchronization or, on
   6 // Windows, simulates it.  This functionality is very helpful for having
   7 // several threads wait for an event, as is common with a thread pool managed
   8 // by a master.  The meaning of such an event in the (worker) thread pool
   9 // scenario is that additional tasks are now available for processing.  It is
  10 // used in Chrome in the DNS prefetching system to notify worker threads that
  11 // a queue now has items (tasks) which need to be tended to.  A related use
  12 // would have a pool manager waiting on a ConditionVariable, waiting for a
  13 // thread in the pool to announce (signal) that there is now more room in a
  14 // (bounded size) communications queue for the manager to deposit tasks, or,
  15 // as a second example, that the queue of tasks is completely empty and all
  16 // workers are waiting.
  17 //
  18 // USAGE NOTE 1: spurious signal events are possible with this and
  19 // most implementations of condition variables.  As a result, be
  20 // *sure* to retest your condition before proceeding.  The following
  21 // is a good example of doing this correctly:
  22 //
  23 // while (!work_to_be_done()) Wait(...);
  24 //
  25 // In contrast do NOT do the following:
  26 //
  27 // if (!work_to_be_done()) Wait(...);  // Don't do this.
  28 //
  29 // Especially avoid the above if you are relying on some other thread only
  30 // issuing a signal up *if* there is work-to-do.  There can/will
  31 // be spurious signals.  Recheck state on waiting thread before
  32 // assuming the signal was intentional. Caveat caller ;-).
  33 //
  34 // USAGE NOTE 2: Broadcast() frees up all waiting threads at once,
  35 // which leads to contention for the locks they all held when they
  36 // called Wait().  This results in POOR performance.  A much better
  37 // approach to getting a lot of threads out of Wait() is to have each
  38 // thread (upon exiting Wait()) call Signal() to free up another
  39 // Wait'ing thread.  Look at condition_variable_unittest.cc for
  40 // both examples.
  41 //
  42 // Broadcast() can be used nicely during teardown, as it gets the job
  43 // done, and leaves no sleeping threads... and performance is less
  44 // critical at that point.
  45 //
  46 // The semantics of Broadcast() are carefully crafted so that *all*
  47 // threads that were waiting when the request was made will indeed
  48 // get signaled.  Some implementations mess up, and don't signal them
  49 // all, while others allow the wait to be effectively turned off (for
  50 // a while while waiting threads come around).  This implementation
  51 // appears correct, as it will not "lose" any signals, and will guarantee
  52 // that all threads get signaled by Broadcast().
  53 //
  54 // This implementation offers support for "performance" in its selection of
  55 // which thread to revive.  Performance, in direct contrast with "fairness,"
  56 // assures that the thread that most recently began to Wait() is selected by
  57 // Signal to revive.  Fairness would (if publicly supported) assure that the
  58 // thread that has Wait()ed the longest is selected. The default policy
  59 // may improve performance, as the selected thread may have a greater chance of
  60 // having some of its stack data in various CPU caches.
  61 //
  62 // For a discussion of the many very subtle implementation details, see the FAQ
  63 // at the end of condition_variable_win.cc.
  64
  65 #ifndef BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_
  66 #define BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_
  67
  68 #include "build/build_config.h"
  69
  70 #if defined(OS_POSIX)
  71 #include <pthread.h>
  72 #endif
  73
  74 #include "base/base_export.h"
  75 #include "base/basictypes.h"
  76 #include "base/synchronization/lock.h"
  77
  78 namespace base {
  79
  80 class ConditionVarImpl;
  81 class TimeDelta;
  82
  83 class BASE_EXPORT ConditionVariable {
  84  public:
  85   // Construct a cv for use with ONLY one user lock.
  86   explicit ConditionVariable(Lock* user_lock);
  87
  88   ~ConditionVariable();
  89
  90   // Wait() releases the caller's critical section atomically as it starts to
  91   // sleep, and the reacquires it when it is signaled.
  92   void Wait();
  93   void TimedWait(const TimeDelta& max_time);
  94
  95   // Broadcast() revives all waiting threads.
  96   void Broadcast();
  97   // Signal() revives one waiting thread.
  98   void Signal();
  99
 100  private:
 101
 102 #if defined(OS_WIN)
 103   ConditionVarImpl* impl_;
 104 #elif defined(OS_POSIX)
 105   pthread_cond_t condition_;
 106   pthread_mutex_t* user_mutex_;
 107 #if !defined(NDEBUG) || defined(DCHECK_ALWAYS_ON)
 108   base::Lock* user_lock_;     // Needed to adjust shadow lock state on wait.
 109 #endif
 110
 111 #endif
 112
 113   DISALLOW_COPY_AND_ASSIGN(ConditionVariable);
 114 };
 115
 116 }  // namespace base
 117
 118 #endif  // BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_