1 // Copyright 2011 The Chromium Authors 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 #ifndef BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_ 63 #define BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_ 64 65 #include "base/dcheck_is_on.h" 66 #include "base/memory/raw_ptr.h" 67 #include "build/build_config.h" 68 69 #if BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 70 #include <pthread.h> 71 #endif 72 73 #include "base/base_export.h" 74 #include "base/synchronization/lock.h" 75 76 #if BUILDFLAG(IS_WIN) 77 #include "base/win/windows_types.h" 78 #endif 79 80 namespace base { 81 82 class TimeDelta; 83 84 class BASE_EXPORT ConditionVariable { 85 public: 86 // Construct a cv for use with ONLY one user lock. 87 explicit ConditionVariable(Lock* user_lock); 88 89 ConditionVariable(const ConditionVariable&) = delete; 90 ConditionVariable& operator=(const ConditionVariable&) = delete; 91 92 ~ConditionVariable(); 93 94 // Wait() releases the caller's critical section atomically as it starts to 95 // sleep, and the reacquires it when it is signaled. The wait functions are 96 // susceptible to spurious wakeups. (See usage note 1 for more details.) 97 NOT_TAIL_CALLED void Wait(); 98 NOT_TAIL_CALLED void TimedWait(const TimeDelta& max_time); 99 100 // Broadcast() revives all waiting threads. (See usage note 2 for more 101 // details.) 102 void Broadcast(); 103 // Signal() revives one waiting thread. 104 void Signal(); 105 106 // Declares that this ConditionVariable will only ever be used by a thread 107 // that is idle at the bottom of its stack and waiting for work (in 108 // particular, it is not synchronously waiting on this ConditionVariable 109 // before resuming ongoing work). This is useful to avoid telling 110 // base-internals that this thread is "blocked" when it's merely idle and 111 // ready to do work. As such, this is only expected to be used by thread and 112 // thread pool impls. declare_only_used_while_idle()113 void declare_only_used_while_idle() { waiting_is_blocking_ = false; } 114 115 private: 116 #if BUILDFLAG(IS_WIN) 117 CHROME_CONDITION_VARIABLE cv_; 118 const raw_ptr<CHROME_SRWLOCK> srwlock_; 119 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA) 120 pthread_cond_t condition_; 121 raw_ptr<pthread_mutex_t> user_mutex_; 122 #endif 123 124 #if DCHECK_IS_ON() 125 const raw_ptr<base::Lock> 126 user_lock_; // Needed to adjust shadow lock state on wait. 127 #endif 128 129 // Whether a thread invoking Wait() on this ConditionalVariable should be 130 // considered blocked as opposed to idle (and potentially replaced if part of 131 // a pool). 132 bool waiting_is_blocking_ = true; 133 }; 134 135 } // namespace base 136 137 #endif // BASE_SYNCHRONIZATION_CONDITION_VARIABLE_H_ 138