| OLD | NEW |
|---|
| (Empty) |
| 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_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
