1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/ipc/chromium/src/base/condition_variable.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,174 @@
1.4 +// Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
1.5 +// Use of this source code is governed by a BSD-style license that can be
1.6 +// found in the LICENSE file.
1.7 +
1.8 +// ConditionVariable wraps pthreads condition variable synchronization or, on
1.9 +// Windows, simulates it. This functionality is very helpful for having
1.10 +// several threads wait for an event, as is common with a thread pool managed
1.11 +// by a master. The meaning of such an event in the (worker) thread pool
1.12 +// scenario is that additional tasks are now available for processing. It is
1.13 +// used in Chrome in the DNS prefetching system to notify worker threads that
1.14 +// a queue now has items (tasks) which need to be tended to. A related use
1.15 +// would have a pool manager waiting on a ConditionVariable, waiting for a
1.16 +// thread in the pool to announce (signal) that there is now more room in a
1.17 +// (bounded size) communications queue for the manager to deposit tasks, or,
1.18 +// as a second example, that the queue of tasks is completely empty and all
1.19 +// workers are waiting.
1.20 +//
1.21 +// USAGE NOTE 1: spurious signal events are possible with this and
1.22 +// most implementations of condition variables. As a result, be
1.23 +// *sure* to retest your condition before proceeding. The following
1.24 +// is a good example of doing this correctly:
1.25 +//
1.26 +// while (!work_to_be_done()) Wait(...);
1.27 +//
1.28 +// In contrast do NOT do the following:
1.29 +//
1.30 +// if (!work_to_be_done()) Wait(...); // Don't do this.
1.31 +//
1.32 +// Especially avoid the above if you are relying on some other thread only
1.33 +// issuing a signal up *if* there is work-to-do. There can/will
1.34 +// be spurious signals. Recheck state on waiting thread before
1.35 +// assuming the signal was intentional. Caveat caller ;-).
1.36 +//
1.37 +// USAGE NOTE 2: Broadcast() frees up all waiting threads at once,
1.38 +// which leads to contention for the locks they all held when they
1.39 +// called Wait(). This results in POOR performance. A much better
1.40 +// approach to getting a lot of threads out of Wait() is to have each
1.41 +// thread (upon exiting Wait()) call Signal() to free up another
1.42 +// Wait'ing thread. Look at condition_variable_unittest.cc for
1.43 +// both examples.
1.44 +//
1.45 +// Broadcast() can be used nicely during teardown, as it gets the job
1.46 +// done, and leaves no sleeping threads... and performance is less
1.47 +// critical at that point.
1.48 +//
1.49 +// The semantics of Broadcast() are carefully crafted so that *all*
1.50 +// threads that were waiting when the request was made will indeed
1.51 +// get signaled. Some implementations mess up, and don't signal them
1.52 +// all, while others allow the wait to be effectively turned off (for
1.53 +// a while while waiting threads come around). This implementation
1.54 +// appears correct, as it will not "lose" any signals, and will guarantee
1.55 +// that all threads get signaled by Broadcast().
1.56 +//
1.57 +// This implementation offers support for "performance" in its selection of
1.58 +// which thread to revive. Performance, in direct contrast with "fairness,"
1.59 +// assures that the thread that most recently began to Wait() is selected by
1.60 +// Signal to revive. Fairness would (if publicly supported) assure that the
1.61 +// thread that has Wait()ed the longest is selected. The default policy
1.62 +// may improve performance, as the selected thread may have a greater chance of
1.63 +// having some of its stack data in various CPU caches.
1.64 +//
1.65 +// For a discussion of the many very subtle implementation details, see the FAQ
1.66 +// at the end of condition_variable_win.cc.
1.67 +
1.68 +#ifndef BASE_CONDITION_VARIABLE_H_
1.69 +#define BASE_CONDITION_VARIABLE_H_
1.70 +
1.71 +#include "base/lock.h"
1.72 +
1.73 +namespace base {
1.74 + class TimeDelta;
1.75 +}
1.76 +
1.77 +class ConditionVariable {
1.78 + public:
1.79 + // Construct a cv for use with ONLY one user lock.
1.80 + explicit ConditionVariable(Lock* user_lock);
1.81 +
1.82 + ~ConditionVariable();
1.83 +
1.84 + // Wait() releases the caller's critical section atomically as it starts to
1.85 + // sleep, and the reacquires it when it is signaled.
1.86 + void Wait();
1.87 + void TimedWait(const base::TimeDelta& max_time);
1.88 +
1.89 + // Broadcast() revives all waiting threads.
1.90 + void Broadcast();
1.91 + // Signal() revives one waiting thread.
1.92 + void Signal();
1.93 +
1.94 + private:
1.95 +
1.96 +#if defined(OS_WIN)
1.97 +
1.98 + // Define Event class that is used to form circularly linked lists.
1.99 + // The list container is an element with NULL as its handle_ value.
1.100 + // The actual list elements have a non-zero handle_ value.
1.101 + // All calls to methods MUST be done under protection of a lock so that links
1.102 + // can be validated. Without the lock, some links might asynchronously
1.103 + // change, and the assertions would fail (as would list change operations).
1.104 + class Event {
1.105 + public:
1.106 + // Default constructor with no arguments creates a list container.
1.107 + Event();
1.108 + ~Event();
1.109 +
1.110 + // InitListElement transitions an instance from a container, to an element.
1.111 + void InitListElement();
1.112 +
1.113 + // Methods for use on lists.
1.114 + bool IsEmpty() const;
1.115 + void PushBack(Event* other);
1.116 + Event* PopFront();
1.117 + Event* PopBack();
1.118 +
1.119 + // Methods for use on list elements.
1.120 + // Accessor method.
1.121 + HANDLE handle() const;
1.122 + // Pull an element from a list (if it's in one).
1.123 + Event* Extract();
1.124 +
1.125 + // Method for use on a list element or on a list.
1.126 + bool IsSingleton() const;
1.127 +
1.128 + private:
1.129 + // Provide pre/post conditions to validate correct manipulations.
1.130 + bool ValidateAsDistinct(Event* other) const;
1.131 + bool ValidateAsItem() const;
1.132 + bool ValidateAsList() const;
1.133 + bool ValidateLinks() const;
1.134 +
1.135 + HANDLE handle_;
1.136 + Event* next_;
1.137 + Event* prev_;
1.138 + DISALLOW_COPY_AND_ASSIGN(Event);
1.139 + };
1.140 +
1.141 + // Note that RUNNING is an unlikely number to have in RAM by accident.
1.142 + // This helps with defensive destructor coding in the face of user error.
1.143 + enum RunState { SHUTDOWN = 0, RUNNING = 64213 };
1.144 +
1.145 + // Internal implementation methods supporting Wait().
1.146 + Event* GetEventForWaiting();
1.147 + void RecycleEvent(Event* used_event);
1.148 +
1.149 + RunState run_state_;
1.150 +
1.151 + // Private critical section for access to member data.
1.152 + Lock internal_lock_;
1.153 +
1.154 + // Lock that is acquired before calling Wait().
1.155 + Lock& user_lock_;
1.156 +
1.157 + // Events that threads are blocked on.
1.158 + Event waiting_list_;
1.159 +
1.160 + // Free list for old events.
1.161 + Event recycling_list_;
1.162 + int recycling_list_size_;
1.163 +
1.164 + // The number of allocated, but not yet deleted events.
1.165 + int allocation_counter_;
1.166 +
1.167 +#elif defined(OS_POSIX)
1.168 +
1.169 + pthread_cond_t condition_;
1.170 + pthread_mutex_t* user_mutex_;
1.171 +
1.172 +#endif
1.173 +
1.174 + DISALLOW_COPY_AND_ASSIGN(ConditionVariable);
1.175 +};
1.176 +
1.177 +#endif // BASE_CONDITION_VARIABLE_H_
