xref: /aosp_15_r20/external/abseil-cpp/absl/synchronization/mutex.h (revision 9356374a3709195abf420251b3e825997ff56c0f)
1*9356374aSAndroid Build Coastguard Worker // Copyright 2017 The Abseil Authors.
2*9356374aSAndroid Build Coastguard Worker //
3*9356374aSAndroid Build Coastguard Worker // Licensed under the Apache License, Version 2.0 (the "License");
4*9356374aSAndroid Build Coastguard Worker // you may not use this file except in compliance with the License.
5*9356374aSAndroid Build Coastguard Worker // You may obtain a copy of the License at
6*9356374aSAndroid Build Coastguard Worker //
7*9356374aSAndroid Build Coastguard Worker //      https://www.apache.org/licenses/LICENSE-2.0
8*9356374aSAndroid Build Coastguard Worker //
9*9356374aSAndroid Build Coastguard Worker // Unless required by applicable law or agreed to in writing, software
10*9356374aSAndroid Build Coastguard Worker // distributed under the License is distributed on an "AS IS" BASIS,
11*9356374aSAndroid Build Coastguard Worker // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12*9356374aSAndroid Build Coastguard Worker // See the License for the specific language governing permissions and
13*9356374aSAndroid Build Coastguard Worker // limitations under the License.
14*9356374aSAndroid Build Coastguard Worker //
15*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
16*9356374aSAndroid Build Coastguard Worker // mutex.h
17*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
18*9356374aSAndroid Build Coastguard Worker //
19*9356374aSAndroid Build Coastguard Worker // This header file defines a `Mutex` -- a mutually exclusive lock -- and the
20*9356374aSAndroid Build Coastguard Worker // most common type of synchronization primitive for facilitating locks on
21*9356374aSAndroid Build Coastguard Worker // shared resources. A mutex is used to prevent multiple threads from accessing
22*9356374aSAndroid Build Coastguard Worker // and/or writing to a shared resource concurrently.
23*9356374aSAndroid Build Coastguard Worker //
24*9356374aSAndroid Build Coastguard Worker // Unlike a `std::mutex`, the Abseil `Mutex` provides the following additional
25*9356374aSAndroid Build Coastguard Worker // features:
26*9356374aSAndroid Build Coastguard Worker //   * Conditional predicates intrinsic to the `Mutex` object
27*9356374aSAndroid Build Coastguard Worker //   * Shared/reader locks, in addition to standard exclusive/writer locks
28*9356374aSAndroid Build Coastguard Worker //   * Deadlock detection and debug support.
29*9356374aSAndroid Build Coastguard Worker //
30*9356374aSAndroid Build Coastguard Worker // The following helper classes are also defined within this file:
31*9356374aSAndroid Build Coastguard Worker //
32*9356374aSAndroid Build Coastguard Worker //  MutexLock - An RAII wrapper to acquire and release a `Mutex` for exclusive/
33*9356374aSAndroid Build Coastguard Worker //              write access within the current scope.
34*9356374aSAndroid Build Coastguard Worker //
35*9356374aSAndroid Build Coastguard Worker //  ReaderMutexLock
36*9356374aSAndroid Build Coastguard Worker //            - An RAII wrapper to acquire and release a `Mutex` for shared/read
37*9356374aSAndroid Build Coastguard Worker //              access within the current scope.
38*9356374aSAndroid Build Coastguard Worker //
39*9356374aSAndroid Build Coastguard Worker //  WriterMutexLock
40*9356374aSAndroid Build Coastguard Worker //            - Effectively an alias for `MutexLock` above, designed for use in
41*9356374aSAndroid Build Coastguard Worker //              distinguishing reader and writer locks within code.
42*9356374aSAndroid Build Coastguard Worker //
43*9356374aSAndroid Build Coastguard Worker // In addition to simple mutex locks, this file also defines ways to perform
44*9356374aSAndroid Build Coastguard Worker // locking under certain conditions.
45*9356374aSAndroid Build Coastguard Worker //
46*9356374aSAndroid Build Coastguard Worker //  Condition - (Preferred) Used to wait for a particular predicate that
47*9356374aSAndroid Build Coastguard Worker //              depends on state protected by the `Mutex` to become true.
48*9356374aSAndroid Build Coastguard Worker //  CondVar   - A lower-level variant of `Condition` that relies on
49*9356374aSAndroid Build Coastguard Worker //              application code to explicitly signal the `CondVar` when
50*9356374aSAndroid Build Coastguard Worker //              a condition has been met.
51*9356374aSAndroid Build Coastguard Worker //
52*9356374aSAndroid Build Coastguard Worker // See below for more information on using `Condition` or `CondVar`.
53*9356374aSAndroid Build Coastguard Worker //
54*9356374aSAndroid Build Coastguard Worker // Mutexes and mutex behavior can be quite complicated. The information within
55*9356374aSAndroid Build Coastguard Worker // this header file is limited, as a result. Please consult the Mutex guide for
56*9356374aSAndroid Build Coastguard Worker // more complete information and examples.
57*9356374aSAndroid Build Coastguard Worker 
58*9356374aSAndroid Build Coastguard Worker #ifndef ABSL_SYNCHRONIZATION_MUTEX_H_
59*9356374aSAndroid Build Coastguard Worker #define ABSL_SYNCHRONIZATION_MUTEX_H_
60*9356374aSAndroid Build Coastguard Worker 
61*9356374aSAndroid Build Coastguard Worker #include <atomic>
62*9356374aSAndroid Build Coastguard Worker #include <cstdint>
63*9356374aSAndroid Build Coastguard Worker #include <cstring>
64*9356374aSAndroid Build Coastguard Worker #include <iterator>
65*9356374aSAndroid Build Coastguard Worker #include <string>
66*9356374aSAndroid Build Coastguard Worker 
67*9356374aSAndroid Build Coastguard Worker #include "absl/base/attributes.h"
68*9356374aSAndroid Build Coastguard Worker #include "absl/base/const_init.h"
69*9356374aSAndroid Build Coastguard Worker #include "absl/base/internal/identity.h"
70*9356374aSAndroid Build Coastguard Worker #include "absl/base/internal/low_level_alloc.h"
71*9356374aSAndroid Build Coastguard Worker #include "absl/base/internal/thread_identity.h"
72*9356374aSAndroid Build Coastguard Worker #include "absl/base/internal/tsan_mutex_interface.h"
73*9356374aSAndroid Build Coastguard Worker #include "absl/base/port.h"
74*9356374aSAndroid Build Coastguard Worker #include "absl/base/thread_annotations.h"
75*9356374aSAndroid Build Coastguard Worker #include "absl/synchronization/internal/kernel_timeout.h"
76*9356374aSAndroid Build Coastguard Worker #include "absl/synchronization/internal/per_thread_sem.h"
77*9356374aSAndroid Build Coastguard Worker #include "absl/time/time.h"
78*9356374aSAndroid Build Coastguard Worker 
79*9356374aSAndroid Build Coastguard Worker namespace absl {
80*9356374aSAndroid Build Coastguard Worker ABSL_NAMESPACE_BEGIN
81*9356374aSAndroid Build Coastguard Worker 
82*9356374aSAndroid Build Coastguard Worker class Condition;
83*9356374aSAndroid Build Coastguard Worker struct SynchWaitParams;
84*9356374aSAndroid Build Coastguard Worker 
85*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
86*9356374aSAndroid Build Coastguard Worker // Mutex
87*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
88*9356374aSAndroid Build Coastguard Worker //
89*9356374aSAndroid Build Coastguard Worker // A `Mutex` is a non-reentrant (aka non-recursive) Mutually Exclusive lock
90*9356374aSAndroid Build Coastguard Worker // on some resource, typically a variable or data structure with associated
91*9356374aSAndroid Build Coastguard Worker // invariants. Proper usage of mutexes prevents concurrent access by different
92*9356374aSAndroid Build Coastguard Worker // threads to the same resource.
93*9356374aSAndroid Build Coastguard Worker //
94*9356374aSAndroid Build Coastguard Worker // A `Mutex` has two basic operations: `Mutex::Lock()` and `Mutex::Unlock()`.
95*9356374aSAndroid Build Coastguard Worker // The `Lock()` operation *acquires* a `Mutex` (in a state known as an
96*9356374aSAndroid Build Coastguard Worker // *exclusive* -- or *write* -- lock), and the `Unlock()` operation *releases* a
97*9356374aSAndroid Build Coastguard Worker // Mutex. During the span of time between the Lock() and Unlock() operations,
98*9356374aSAndroid Build Coastguard Worker // a mutex is said to be *held*. By design, all mutexes support exclusive/write
99*9356374aSAndroid Build Coastguard Worker // locks, as this is the most common way to use a mutex.
100*9356374aSAndroid Build Coastguard Worker //
101*9356374aSAndroid Build Coastguard Worker // Mutex operations are only allowed under certain conditions; otherwise an
102*9356374aSAndroid Build Coastguard Worker // operation is "invalid", and disallowed by the API. The conditions concern
103*9356374aSAndroid Build Coastguard Worker // both the current state of the mutex and the identity of the threads that
104*9356374aSAndroid Build Coastguard Worker // are performing the operations.
105*9356374aSAndroid Build Coastguard Worker //
106*9356374aSAndroid Build Coastguard Worker // The `Mutex` state machine for basic lock/unlock operations is quite simple:
107*9356374aSAndroid Build Coastguard Worker //
108*9356374aSAndroid Build Coastguard Worker // |                | Lock()                 | Unlock() |
109*9356374aSAndroid Build Coastguard Worker // |----------------+------------------------+----------|
110*9356374aSAndroid Build Coastguard Worker // | Free           | Exclusive              | invalid  |
111*9356374aSAndroid Build Coastguard Worker // | Exclusive      | blocks, then exclusive | Free     |
112*9356374aSAndroid Build Coastguard Worker //
113*9356374aSAndroid Build Coastguard Worker // The full conditions are as follows.
114*9356374aSAndroid Build Coastguard Worker //
115*9356374aSAndroid Build Coastguard Worker // * Calls to `Unlock()` require that the mutex be held, and must be made in the
116*9356374aSAndroid Build Coastguard Worker //   same thread that performed the corresponding `Lock()` operation which
117*9356374aSAndroid Build Coastguard Worker //   acquired the mutex; otherwise the call is invalid.
118*9356374aSAndroid Build Coastguard Worker //
119*9356374aSAndroid Build Coastguard Worker // * The mutex being non-reentrant (or non-recursive) means that a call to
120*9356374aSAndroid Build Coastguard Worker //   `Lock()` or `TryLock()` must not be made in a thread that already holds the
121*9356374aSAndroid Build Coastguard Worker //   mutex; such a call is invalid.
122*9356374aSAndroid Build Coastguard Worker //
123*9356374aSAndroid Build Coastguard Worker // * In other words, the state of being "held" has both a temporal component
124*9356374aSAndroid Build Coastguard Worker //   (from `Lock()` until `Unlock()`) as well as a thread identity component:
125*9356374aSAndroid Build Coastguard Worker //   the mutex is held *by a particular thread*.
126*9356374aSAndroid Build Coastguard Worker //
127*9356374aSAndroid Build Coastguard Worker // An "invalid" operation has undefined behavior. The `Mutex` implementation
128*9356374aSAndroid Build Coastguard Worker // is allowed to do anything on an invalid call, including, but not limited to,
129*9356374aSAndroid Build Coastguard Worker // crashing with a useful error message, silently succeeding, or corrupting
130*9356374aSAndroid Build Coastguard Worker // data structures. In debug mode, the implementation may crash with a useful
131*9356374aSAndroid Build Coastguard Worker // error message.
132*9356374aSAndroid Build Coastguard Worker //
133*9356374aSAndroid Build Coastguard Worker // `Mutex` is not guaranteed to be "fair" in prioritizing waiting threads; it
134*9356374aSAndroid Build Coastguard Worker // is, however, approximately fair over long periods, and starvation-free for
135*9356374aSAndroid Build Coastguard Worker // threads at the same priority.
136*9356374aSAndroid Build Coastguard Worker //
137*9356374aSAndroid Build Coastguard Worker // The lock/unlock primitives are now annotated with lock annotations
138*9356374aSAndroid Build Coastguard Worker // defined in (base/thread_annotations.h). When writing multi-threaded code,
139*9356374aSAndroid Build Coastguard Worker // you should use lock annotations whenever possible to document your lock
140*9356374aSAndroid Build Coastguard Worker // synchronization policy. Besides acting as documentation, these annotations
141*9356374aSAndroid Build Coastguard Worker // also help compilers or static analysis tools to identify and warn about
142*9356374aSAndroid Build Coastguard Worker // issues that could potentially result in race conditions and deadlocks.
143*9356374aSAndroid Build Coastguard Worker //
144*9356374aSAndroid Build Coastguard Worker // For more information about the lock annotations, please see
145*9356374aSAndroid Build Coastguard Worker // [Thread Safety
146*9356374aSAndroid Build Coastguard Worker // Analysis](http://clang.llvm.org/docs/ThreadSafetyAnalysis.html) in the Clang
147*9356374aSAndroid Build Coastguard Worker // documentation.
148*9356374aSAndroid Build Coastguard Worker //
149*9356374aSAndroid Build Coastguard Worker // See also `MutexLock`, below, for scoped `Mutex` acquisition.
150*9356374aSAndroid Build Coastguard Worker 
151*9356374aSAndroid Build Coastguard Worker class ABSL_LOCKABLE ABSL_ATTRIBUTE_WARN_UNUSED Mutex {
152*9356374aSAndroid Build Coastguard Worker  public:
153*9356374aSAndroid Build Coastguard Worker   // Creates a `Mutex` that is not held by anyone. This constructor is
154*9356374aSAndroid Build Coastguard Worker   // typically used for Mutexes allocated on the heap or the stack.
155*9356374aSAndroid Build Coastguard Worker   //
156*9356374aSAndroid Build Coastguard Worker   // To create `Mutex` instances with static storage duration
157*9356374aSAndroid Build Coastguard Worker   // (e.g. a namespace-scoped or global variable), see
158*9356374aSAndroid Build Coastguard Worker   // `Mutex::Mutex(absl::kConstInit)` below instead.
159*9356374aSAndroid Build Coastguard Worker   Mutex();
160*9356374aSAndroid Build Coastguard Worker 
161*9356374aSAndroid Build Coastguard Worker   // Creates a mutex with static storage duration.  A global variable
162*9356374aSAndroid Build Coastguard Worker   // constructed this way avoids the lifetime issues that can occur on program
163*9356374aSAndroid Build Coastguard Worker   // startup and shutdown.  (See absl/base/const_init.h.)
164*9356374aSAndroid Build Coastguard Worker   //
165*9356374aSAndroid Build Coastguard Worker   // For Mutexes allocated on the heap and stack, instead use the default
166*9356374aSAndroid Build Coastguard Worker   // constructor, which can interact more fully with the thread sanitizer.
167*9356374aSAndroid Build Coastguard Worker   //
168*9356374aSAndroid Build Coastguard Worker   // Example usage:
169*9356374aSAndroid Build Coastguard Worker   //   namespace foo {
170*9356374aSAndroid Build Coastguard Worker   //   ABSL_CONST_INIT absl::Mutex mu(absl::kConstInit);
171*9356374aSAndroid Build Coastguard Worker   //   }
172*9356374aSAndroid Build Coastguard Worker   explicit constexpr Mutex(absl::ConstInitType);
173*9356374aSAndroid Build Coastguard Worker 
174*9356374aSAndroid Build Coastguard Worker   ~Mutex();
175*9356374aSAndroid Build Coastguard Worker 
176*9356374aSAndroid Build Coastguard Worker   // Mutex::Lock()
177*9356374aSAndroid Build Coastguard Worker   //
178*9356374aSAndroid Build Coastguard Worker   // Blocks the calling thread, if necessary, until this `Mutex` is free, and
179*9356374aSAndroid Build Coastguard Worker   // then acquires it exclusively. (This lock is also known as a "write lock.")
180*9356374aSAndroid Build Coastguard Worker   void Lock() ABSL_EXCLUSIVE_LOCK_FUNCTION();
181*9356374aSAndroid Build Coastguard Worker 
182*9356374aSAndroid Build Coastguard Worker   // Mutex::Unlock()
183*9356374aSAndroid Build Coastguard Worker   //
184*9356374aSAndroid Build Coastguard Worker   // Releases this `Mutex` and returns it from the exclusive/write state to the
185*9356374aSAndroid Build Coastguard Worker   // free state. Calling thread must hold the `Mutex` exclusively.
186*9356374aSAndroid Build Coastguard Worker   void Unlock() ABSL_UNLOCK_FUNCTION();
187*9356374aSAndroid Build Coastguard Worker 
188*9356374aSAndroid Build Coastguard Worker   // Mutex::TryLock()
189*9356374aSAndroid Build Coastguard Worker   //
190*9356374aSAndroid Build Coastguard Worker   // If the mutex can be acquired without blocking, does so exclusively and
191*9356374aSAndroid Build Coastguard Worker   // returns `true`. Otherwise, returns `false`. Returns `true` with high
192*9356374aSAndroid Build Coastguard Worker   // probability if the `Mutex` was free.
193*9356374aSAndroid Build Coastguard Worker   ABSL_MUST_USE_RESULT bool TryLock() ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true);
194*9356374aSAndroid Build Coastguard Worker 
195*9356374aSAndroid Build Coastguard Worker   // Mutex::AssertHeld()
196*9356374aSAndroid Build Coastguard Worker   //
197*9356374aSAndroid Build Coastguard Worker   // Require that the mutex be held exclusively (write mode) by this thread.
198*9356374aSAndroid Build Coastguard Worker   //
199*9356374aSAndroid Build Coastguard Worker   // If the mutex is not currently held by this thread, this function may report
200*9356374aSAndroid Build Coastguard Worker   // an error (typically by crashing with a diagnostic) or it may do nothing.
201*9356374aSAndroid Build Coastguard Worker   // This function is intended only as a tool to assist debugging; it doesn't
202*9356374aSAndroid Build Coastguard Worker   // guarantee correctness.
203*9356374aSAndroid Build Coastguard Worker   void AssertHeld() const ABSL_ASSERT_EXCLUSIVE_LOCK();
204*9356374aSAndroid Build Coastguard Worker 
205*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
206*9356374aSAndroid Build Coastguard Worker   // Reader-Writer Locking
207*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
208*9356374aSAndroid Build Coastguard Worker 
209*9356374aSAndroid Build Coastguard Worker   // A Mutex can also be used as a starvation-free reader-writer lock.
210*9356374aSAndroid Build Coastguard Worker   // Neither read-locks nor write-locks are reentrant/recursive to avoid
211*9356374aSAndroid Build Coastguard Worker   // potential client programming errors.
212*9356374aSAndroid Build Coastguard Worker   //
213*9356374aSAndroid Build Coastguard Worker   // The Mutex API provides `Writer*()` aliases for the existing `Lock()`,
214*9356374aSAndroid Build Coastguard Worker   // `Unlock()` and `TryLock()` methods for use within applications mixing
215*9356374aSAndroid Build Coastguard Worker   // reader/writer locks. Using `Reader*()` and `Writer*()` operations in this
216*9356374aSAndroid Build Coastguard Worker   // manner can make locking behavior clearer when mixing read and write modes.
217*9356374aSAndroid Build Coastguard Worker   //
218*9356374aSAndroid Build Coastguard Worker   // Introducing reader locks necessarily complicates the `Mutex` state
219*9356374aSAndroid Build Coastguard Worker   // machine somewhat. The table below illustrates the allowed state transitions
220*9356374aSAndroid Build Coastguard Worker   // of a mutex in such cases. Note that ReaderLock() may block even if the lock
221*9356374aSAndroid Build Coastguard Worker   // is held in shared mode; this occurs when another thread is blocked on a
222*9356374aSAndroid Build Coastguard Worker   // call to WriterLock().
223*9356374aSAndroid Build Coastguard Worker   //
224*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
225*9356374aSAndroid Build Coastguard Worker   //     Operation: WriterLock() Unlock()  ReaderLock()           ReaderUnlock()
226*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
227*9356374aSAndroid Build Coastguard Worker   // State
228*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
229*9356374aSAndroid Build Coastguard Worker   // Free           Exclusive    invalid   Shared(1)              invalid
230*9356374aSAndroid Build Coastguard Worker   // Shared(1)      blocks       invalid   Shared(2) or blocks    Free
231*9356374aSAndroid Build Coastguard Worker   // Shared(n) n>1  blocks       invalid   Shared(n+1) or blocks  Shared(n-1)
232*9356374aSAndroid Build Coastguard Worker   // Exclusive      blocks       Free      blocks                 invalid
233*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
234*9356374aSAndroid Build Coastguard Worker   //
235*9356374aSAndroid Build Coastguard Worker   // In comments below, "shared" refers to a state of Shared(n) for any n > 0.
236*9356374aSAndroid Build Coastguard Worker 
237*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderLock()
238*9356374aSAndroid Build Coastguard Worker   //
239*9356374aSAndroid Build Coastguard Worker   // Blocks the calling thread, if necessary, until this `Mutex` is either free,
240*9356374aSAndroid Build Coastguard Worker   // or in shared mode, and then acquires a share of it. Note that
241*9356374aSAndroid Build Coastguard Worker   // `ReaderLock()` will block if some other thread has an exclusive/writer lock
242*9356374aSAndroid Build Coastguard Worker   // on the mutex.
243*9356374aSAndroid Build Coastguard Worker 
244*9356374aSAndroid Build Coastguard Worker   void ReaderLock() ABSL_SHARED_LOCK_FUNCTION();
245*9356374aSAndroid Build Coastguard Worker 
246*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderUnlock()
247*9356374aSAndroid Build Coastguard Worker   //
248*9356374aSAndroid Build Coastguard Worker   // Releases a read share of this `Mutex`. `ReaderUnlock` may return a mutex to
249*9356374aSAndroid Build Coastguard Worker   // the free state if this thread holds the last reader lock on the mutex. Note
250*9356374aSAndroid Build Coastguard Worker   // that you cannot call `ReaderUnlock()` on a mutex held in write mode.
251*9356374aSAndroid Build Coastguard Worker   void ReaderUnlock() ABSL_UNLOCK_FUNCTION();
252*9356374aSAndroid Build Coastguard Worker 
253*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderTryLock()
254*9356374aSAndroid Build Coastguard Worker   //
255*9356374aSAndroid Build Coastguard Worker   // If the mutex can be acquired without blocking, acquires this mutex for
256*9356374aSAndroid Build Coastguard Worker   // shared access and returns `true`. Otherwise, returns `false`. Returns
257*9356374aSAndroid Build Coastguard Worker   // `true` with high probability if the `Mutex` was free or shared.
258*9356374aSAndroid Build Coastguard Worker   ABSL_MUST_USE_RESULT bool ReaderTryLock() ABSL_SHARED_TRYLOCK_FUNCTION(true);
259*9356374aSAndroid Build Coastguard Worker 
260*9356374aSAndroid Build Coastguard Worker   // Mutex::AssertReaderHeld()
261*9356374aSAndroid Build Coastguard Worker   //
262*9356374aSAndroid Build Coastguard Worker   // Require that the mutex be held at least in shared mode (read mode) by this
263*9356374aSAndroid Build Coastguard Worker   // thread.
264*9356374aSAndroid Build Coastguard Worker   //
265*9356374aSAndroid Build Coastguard Worker   // If the mutex is not currently held by this thread, this function may report
266*9356374aSAndroid Build Coastguard Worker   // an error (typically by crashing with a diagnostic) or it may do nothing.
267*9356374aSAndroid Build Coastguard Worker   // This function is intended only as a tool to assist debugging; it doesn't
268*9356374aSAndroid Build Coastguard Worker   // guarantee correctness.
269*9356374aSAndroid Build Coastguard Worker   void AssertReaderHeld() const ABSL_ASSERT_SHARED_LOCK();
270*9356374aSAndroid Build Coastguard Worker 
271*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterLock()
272*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterUnlock()
273*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterTryLock()
274*9356374aSAndroid Build Coastguard Worker   //
275*9356374aSAndroid Build Coastguard Worker   // Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.
276*9356374aSAndroid Build Coastguard Worker   //
277*9356374aSAndroid Build Coastguard Worker   // These methods may be used (along with the complementary `Reader*()`
278*9356374aSAndroid Build Coastguard Worker   // methods) to distinguish simple exclusive `Mutex` usage (`Lock()`,
279*9356374aSAndroid Build Coastguard Worker   // etc.) from reader/writer lock usage.
WriterLock()280*9356374aSAndroid Build Coastguard Worker   void WriterLock() ABSL_EXCLUSIVE_LOCK_FUNCTION() { this->Lock(); }
281*9356374aSAndroid Build Coastguard Worker 
WriterUnlock()282*9356374aSAndroid Build Coastguard Worker   void WriterUnlock() ABSL_UNLOCK_FUNCTION() { this->Unlock(); }
283*9356374aSAndroid Build Coastguard Worker 
WriterTryLock()284*9356374aSAndroid Build Coastguard Worker   ABSL_MUST_USE_RESULT bool WriterTryLock()
285*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_TRYLOCK_FUNCTION(true) {
286*9356374aSAndroid Build Coastguard Worker     return this->TryLock();
287*9356374aSAndroid Build Coastguard Worker   }
288*9356374aSAndroid Build Coastguard Worker 
289*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
290*9356374aSAndroid Build Coastguard Worker   // Conditional Critical Regions
291*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
292*9356374aSAndroid Build Coastguard Worker 
293*9356374aSAndroid Build Coastguard Worker   // Conditional usage of a `Mutex` can occur using two distinct paradigms:
294*9356374aSAndroid Build Coastguard Worker   //
295*9356374aSAndroid Build Coastguard Worker   //   * Use of `Mutex` member functions with `Condition` objects.
296*9356374aSAndroid Build Coastguard Worker   //   * Use of the separate `CondVar` abstraction.
297*9356374aSAndroid Build Coastguard Worker   //
298*9356374aSAndroid Build Coastguard Worker   // In general, prefer use of `Condition` and the `Mutex` member functions
299*9356374aSAndroid Build Coastguard Worker   // listed below over `CondVar`. When there are multiple threads waiting on
300*9356374aSAndroid Build Coastguard Worker   // distinctly different conditions, however, a battery of `CondVar`s may be
301*9356374aSAndroid Build Coastguard Worker   // more efficient. This section discusses use of `Condition` objects.
302*9356374aSAndroid Build Coastguard Worker   //
303*9356374aSAndroid Build Coastguard Worker   // `Mutex` contains member functions for performing lock operations only under
304*9356374aSAndroid Build Coastguard Worker   // certain conditions, of class `Condition`. For correctness, the `Condition`
305*9356374aSAndroid Build Coastguard Worker   // must return a boolean that is a pure function, only of state protected by
306*9356374aSAndroid Build Coastguard Worker   // the `Mutex`. The condition must be invariant w.r.t. environmental state
307*9356374aSAndroid Build Coastguard Worker   // such as thread, cpu id, or time, and must be `noexcept`. The condition will
308*9356374aSAndroid Build Coastguard Worker   // always be invoked with the mutex held in at least read mode, so you should
309*9356374aSAndroid Build Coastguard Worker   // not block it for long periods or sleep it on a timer.
310*9356374aSAndroid Build Coastguard Worker   //
311*9356374aSAndroid Build Coastguard Worker   // Since a condition must not depend directly on the current time, use
312*9356374aSAndroid Build Coastguard Worker   // `*WithTimeout()` member function variants to make your condition
313*9356374aSAndroid Build Coastguard Worker   // effectively true after a given duration, or `*WithDeadline()` variants to
314*9356374aSAndroid Build Coastguard Worker   // make your condition effectively true after a given time.
315*9356374aSAndroid Build Coastguard Worker   //
316*9356374aSAndroid Build Coastguard Worker   // The condition function should have no side-effects aside from debug
317*9356374aSAndroid Build Coastguard Worker   // logging; as a special exception, the function may acquire other mutexes
318*9356374aSAndroid Build Coastguard Worker   // provided it releases all those that it acquires.  (This exception was
319*9356374aSAndroid Build Coastguard Worker   // required to allow logging.)
320*9356374aSAndroid Build Coastguard Worker 
321*9356374aSAndroid Build Coastguard Worker   // Mutex::Await()
322*9356374aSAndroid Build Coastguard Worker   //
323*9356374aSAndroid Build Coastguard Worker   // Unlocks this `Mutex` and blocks until simultaneously both `cond` is `true`
324*9356374aSAndroid Build Coastguard Worker   // and this `Mutex` can be reacquired, then reacquires this `Mutex` in the
325*9356374aSAndroid Build Coastguard Worker   // same mode in which it was previously held. If the condition is initially
326*9356374aSAndroid Build Coastguard Worker   // `true`, `Await()` *may* skip the release/re-acquire step.
327*9356374aSAndroid Build Coastguard Worker   //
328*9356374aSAndroid Build Coastguard Worker   // `Await()` requires that this thread holds this `Mutex` in some mode.
Await(const Condition & cond)329*9356374aSAndroid Build Coastguard Worker   void Await(const Condition& cond) {
330*9356374aSAndroid Build Coastguard Worker     AwaitCommon(cond, synchronization_internal::KernelTimeout::Never());
331*9356374aSAndroid Build Coastguard Worker   }
332*9356374aSAndroid Build Coastguard Worker 
333*9356374aSAndroid Build Coastguard Worker   // Mutex::LockWhen()
334*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderLockWhen()
335*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterLockWhen()
336*9356374aSAndroid Build Coastguard Worker   //
337*9356374aSAndroid Build Coastguard Worker   // Blocks until simultaneously both `cond` is `true` and this `Mutex` can
338*9356374aSAndroid Build Coastguard Worker   // be acquired, then atomically acquires this `Mutex`. `LockWhen()` is
339*9356374aSAndroid Build Coastguard Worker   // logically equivalent to `*Lock(); Await();` though they may have different
340*9356374aSAndroid Build Coastguard Worker   // performance characteristics.
LockWhen(const Condition & cond)341*9356374aSAndroid Build Coastguard Worker   void LockWhen(const Condition& cond) ABSL_EXCLUSIVE_LOCK_FUNCTION() {
342*9356374aSAndroid Build Coastguard Worker     LockWhenCommon(cond, synchronization_internal::KernelTimeout::Never(),
343*9356374aSAndroid Build Coastguard Worker                    true);
344*9356374aSAndroid Build Coastguard Worker   }
345*9356374aSAndroid Build Coastguard Worker 
ReaderLockWhen(const Condition & cond)346*9356374aSAndroid Build Coastguard Worker   void ReaderLockWhen(const Condition& cond) ABSL_SHARED_LOCK_FUNCTION() {
347*9356374aSAndroid Build Coastguard Worker     LockWhenCommon(cond, synchronization_internal::KernelTimeout::Never(),
348*9356374aSAndroid Build Coastguard Worker                    false);
349*9356374aSAndroid Build Coastguard Worker   }
350*9356374aSAndroid Build Coastguard Worker 
WriterLockWhen(const Condition & cond)351*9356374aSAndroid Build Coastguard Worker   void WriterLockWhen(const Condition& cond) ABSL_EXCLUSIVE_LOCK_FUNCTION() {
352*9356374aSAndroid Build Coastguard Worker     this->LockWhen(cond);
353*9356374aSAndroid Build Coastguard Worker   }
354*9356374aSAndroid Build Coastguard Worker 
355*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
356*9356374aSAndroid Build Coastguard Worker   // Mutex Variants with Timeouts/Deadlines
357*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
358*9356374aSAndroid Build Coastguard Worker 
359*9356374aSAndroid Build Coastguard Worker   // Mutex::AwaitWithTimeout()
360*9356374aSAndroid Build Coastguard Worker   // Mutex::AwaitWithDeadline()
361*9356374aSAndroid Build Coastguard Worker   //
362*9356374aSAndroid Build Coastguard Worker   // Unlocks this `Mutex` and blocks until simultaneously:
363*9356374aSAndroid Build Coastguard Worker   //   - either `cond` is true or the {timeout has expired, deadline has passed}
364*9356374aSAndroid Build Coastguard Worker   //     and
365*9356374aSAndroid Build Coastguard Worker   //   - this `Mutex` can be reacquired,
366*9356374aSAndroid Build Coastguard Worker   // then reacquire this `Mutex` in the same mode in which it was previously
367*9356374aSAndroid Build Coastguard Worker   // held, returning `true` iff `cond` is `true` on return.
368*9356374aSAndroid Build Coastguard Worker   //
369*9356374aSAndroid Build Coastguard Worker   // If the condition is initially `true`, the implementation *may* skip the
370*9356374aSAndroid Build Coastguard Worker   // release/re-acquire step and return immediately.
371*9356374aSAndroid Build Coastguard Worker   //
372*9356374aSAndroid Build Coastguard Worker   // Deadlines in the past are equivalent to an immediate deadline.
373*9356374aSAndroid Build Coastguard Worker   // Negative timeouts are equivalent to a zero timeout.
374*9356374aSAndroid Build Coastguard Worker   //
375*9356374aSAndroid Build Coastguard Worker   // This method requires that this thread holds this `Mutex` in some mode.
AwaitWithTimeout(const Condition & cond,absl::Duration timeout)376*9356374aSAndroid Build Coastguard Worker   bool AwaitWithTimeout(const Condition& cond, absl::Duration timeout) {
377*9356374aSAndroid Build Coastguard Worker     return AwaitCommon(cond, synchronization_internal::KernelTimeout{timeout});
378*9356374aSAndroid Build Coastguard Worker   }
379*9356374aSAndroid Build Coastguard Worker 
AwaitWithDeadline(const Condition & cond,absl::Time deadline)380*9356374aSAndroid Build Coastguard Worker   bool AwaitWithDeadline(const Condition& cond, absl::Time deadline) {
381*9356374aSAndroid Build Coastguard Worker     return AwaitCommon(cond, synchronization_internal::KernelTimeout{deadline});
382*9356374aSAndroid Build Coastguard Worker   }
383*9356374aSAndroid Build Coastguard Worker 
384*9356374aSAndroid Build Coastguard Worker   // Mutex::LockWhenWithTimeout()
385*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderLockWhenWithTimeout()
386*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterLockWhenWithTimeout()
387*9356374aSAndroid Build Coastguard Worker   //
388*9356374aSAndroid Build Coastguard Worker   // Blocks until simultaneously both:
389*9356374aSAndroid Build Coastguard Worker   //   - either `cond` is `true` or the timeout has expired, and
390*9356374aSAndroid Build Coastguard Worker   //   - this `Mutex` can be acquired,
391*9356374aSAndroid Build Coastguard Worker   // then atomically acquires this `Mutex`, returning `true` iff `cond` is
392*9356374aSAndroid Build Coastguard Worker   // `true` on return.
393*9356374aSAndroid Build Coastguard Worker   //
394*9356374aSAndroid Build Coastguard Worker   // Negative timeouts are equivalent to a zero timeout.
LockWhenWithTimeout(const Condition & cond,absl::Duration timeout)395*9356374aSAndroid Build Coastguard Worker   bool LockWhenWithTimeout(const Condition& cond, absl::Duration timeout)
396*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION() {
397*9356374aSAndroid Build Coastguard Worker     return LockWhenCommon(
398*9356374aSAndroid Build Coastguard Worker         cond, synchronization_internal::KernelTimeout{timeout}, true);
399*9356374aSAndroid Build Coastguard Worker   }
ReaderLockWhenWithTimeout(const Condition & cond,absl::Duration timeout)400*9356374aSAndroid Build Coastguard Worker   bool ReaderLockWhenWithTimeout(const Condition& cond, absl::Duration timeout)
401*9356374aSAndroid Build Coastguard Worker       ABSL_SHARED_LOCK_FUNCTION() {
402*9356374aSAndroid Build Coastguard Worker     return LockWhenCommon(
403*9356374aSAndroid Build Coastguard Worker         cond, synchronization_internal::KernelTimeout{timeout}, false);
404*9356374aSAndroid Build Coastguard Worker   }
WriterLockWhenWithTimeout(const Condition & cond,absl::Duration timeout)405*9356374aSAndroid Build Coastguard Worker   bool WriterLockWhenWithTimeout(const Condition& cond, absl::Duration timeout)
406*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION() {
407*9356374aSAndroid Build Coastguard Worker     return this->LockWhenWithTimeout(cond, timeout);
408*9356374aSAndroid Build Coastguard Worker   }
409*9356374aSAndroid Build Coastguard Worker 
410*9356374aSAndroid Build Coastguard Worker   // Mutex::LockWhenWithDeadline()
411*9356374aSAndroid Build Coastguard Worker   // Mutex::ReaderLockWhenWithDeadline()
412*9356374aSAndroid Build Coastguard Worker   // Mutex::WriterLockWhenWithDeadline()
413*9356374aSAndroid Build Coastguard Worker   //
414*9356374aSAndroid Build Coastguard Worker   // Blocks until simultaneously both:
415*9356374aSAndroid Build Coastguard Worker   //   - either `cond` is `true` or the deadline has been passed, and
416*9356374aSAndroid Build Coastguard Worker   //   - this `Mutex` can be acquired,
417*9356374aSAndroid Build Coastguard Worker   // then atomically acquires this Mutex, returning `true` iff `cond` is `true`
418*9356374aSAndroid Build Coastguard Worker   // on return.
419*9356374aSAndroid Build Coastguard Worker   //
420*9356374aSAndroid Build Coastguard Worker   // Deadlines in the past are equivalent to an immediate deadline.
LockWhenWithDeadline(const Condition & cond,absl::Time deadline)421*9356374aSAndroid Build Coastguard Worker   bool LockWhenWithDeadline(const Condition& cond, absl::Time deadline)
422*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION() {
423*9356374aSAndroid Build Coastguard Worker     return LockWhenCommon(
424*9356374aSAndroid Build Coastguard Worker         cond, synchronization_internal::KernelTimeout{deadline}, true);
425*9356374aSAndroid Build Coastguard Worker   }
ReaderLockWhenWithDeadline(const Condition & cond,absl::Time deadline)426*9356374aSAndroid Build Coastguard Worker   bool ReaderLockWhenWithDeadline(const Condition& cond, absl::Time deadline)
427*9356374aSAndroid Build Coastguard Worker       ABSL_SHARED_LOCK_FUNCTION() {
428*9356374aSAndroid Build Coastguard Worker     return LockWhenCommon(
429*9356374aSAndroid Build Coastguard Worker         cond, synchronization_internal::KernelTimeout{deadline}, false);
430*9356374aSAndroid Build Coastguard Worker   }
WriterLockWhenWithDeadline(const Condition & cond,absl::Time deadline)431*9356374aSAndroid Build Coastguard Worker   bool WriterLockWhenWithDeadline(const Condition& cond, absl::Time deadline)
432*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION() {
433*9356374aSAndroid Build Coastguard Worker     return this->LockWhenWithDeadline(cond, deadline);
434*9356374aSAndroid Build Coastguard Worker   }
435*9356374aSAndroid Build Coastguard Worker 
436*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
437*9356374aSAndroid Build Coastguard Worker   // Debug Support: Invariant Checking, Deadlock Detection, Logging.
438*9356374aSAndroid Build Coastguard Worker   // ---------------------------------------------------------------------------
439*9356374aSAndroid Build Coastguard Worker 
440*9356374aSAndroid Build Coastguard Worker   // Mutex::EnableInvariantDebugging()
441*9356374aSAndroid Build Coastguard Worker   //
442*9356374aSAndroid Build Coastguard Worker   // If `invariant`!=null and if invariant debugging has been enabled globally,
443*9356374aSAndroid Build Coastguard Worker   // cause `(*invariant)(arg)` to be called at moments when the invariant for
444*9356374aSAndroid Build Coastguard Worker   // this `Mutex` should hold (for example: just after acquire, just before
445*9356374aSAndroid Build Coastguard Worker   // release).
446*9356374aSAndroid Build Coastguard Worker   //
447*9356374aSAndroid Build Coastguard Worker   // The routine `invariant` should have no side-effects since it is not
448*9356374aSAndroid Build Coastguard Worker   // guaranteed how many times it will be called; it should check the invariant
449*9356374aSAndroid Build Coastguard Worker   // and crash if it does not hold. Enabling global invariant debugging may
450*9356374aSAndroid Build Coastguard Worker   // substantially reduce `Mutex` performance; it should be set only for
451*9356374aSAndroid Build Coastguard Worker   // non-production runs.  Optimization options may also disable invariant
452*9356374aSAndroid Build Coastguard Worker   // checks.
453*9356374aSAndroid Build Coastguard Worker   void EnableInvariantDebugging(void (*invariant)(void*), void* arg);
454*9356374aSAndroid Build Coastguard Worker 
455*9356374aSAndroid Build Coastguard Worker   // Mutex::EnableDebugLog()
456*9356374aSAndroid Build Coastguard Worker   //
457*9356374aSAndroid Build Coastguard Worker   // Cause all subsequent uses of this `Mutex` to be logged via
458*9356374aSAndroid Build Coastguard Worker   // `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if no previous
459*9356374aSAndroid Build Coastguard Worker   // call to `EnableInvariantDebugging()` or `EnableDebugLog()` has been made.
460*9356374aSAndroid Build Coastguard Worker   //
461*9356374aSAndroid Build Coastguard Worker   // Note: This method substantially reduces `Mutex` performance.
462*9356374aSAndroid Build Coastguard Worker   void EnableDebugLog(const char* name);
463*9356374aSAndroid Build Coastguard Worker 
464*9356374aSAndroid Build Coastguard Worker   // Deadlock detection
465*9356374aSAndroid Build Coastguard Worker 
466*9356374aSAndroid Build Coastguard Worker   // Mutex::ForgetDeadlockInfo()
467*9356374aSAndroid Build Coastguard Worker   //
468*9356374aSAndroid Build Coastguard Worker   // Forget any deadlock-detection information previously gathered
469*9356374aSAndroid Build Coastguard Worker   // about this `Mutex`. Call this method in debug mode when the lock ordering
470*9356374aSAndroid Build Coastguard Worker   // of a `Mutex` changes.
471*9356374aSAndroid Build Coastguard Worker   void ForgetDeadlockInfo();
472*9356374aSAndroid Build Coastguard Worker 
473*9356374aSAndroid Build Coastguard Worker   // Mutex::AssertNotHeld()
474*9356374aSAndroid Build Coastguard Worker   //
475*9356374aSAndroid Build Coastguard Worker   // Return immediately if this thread does not hold this `Mutex` in any
476*9356374aSAndroid Build Coastguard Worker   // mode; otherwise, may report an error (typically by crashing with a
477*9356374aSAndroid Build Coastguard Worker   // diagnostic), or may return immediately.
478*9356374aSAndroid Build Coastguard Worker   //
479*9356374aSAndroid Build Coastguard Worker   // Currently this check is performed only if all of:
480*9356374aSAndroid Build Coastguard Worker   //    - in debug mode
481*9356374aSAndroid Build Coastguard Worker   //    - SetMutexDeadlockDetectionMode() has been set to kReport or kAbort
482*9356374aSAndroid Build Coastguard Worker   //    - number of locks concurrently held by this thread is not large.
483*9356374aSAndroid Build Coastguard Worker   // are true.
484*9356374aSAndroid Build Coastguard Worker   void AssertNotHeld() const;
485*9356374aSAndroid Build Coastguard Worker 
486*9356374aSAndroid Build Coastguard Worker   // Special cases.
487*9356374aSAndroid Build Coastguard Worker 
488*9356374aSAndroid Build Coastguard Worker   // A `MuHow` is a constant that indicates how a lock should be acquired.
489*9356374aSAndroid Build Coastguard Worker   // Internal implementation detail.  Clients should ignore.
490*9356374aSAndroid Build Coastguard Worker   typedef const struct MuHowS* MuHow;
491*9356374aSAndroid Build Coastguard Worker 
492*9356374aSAndroid Build Coastguard Worker   // Mutex::InternalAttemptToUseMutexInFatalSignalHandler()
493*9356374aSAndroid Build Coastguard Worker   //
494*9356374aSAndroid Build Coastguard Worker   // Causes the `Mutex` implementation to prepare itself for re-entry caused by
495*9356374aSAndroid Build Coastguard Worker   // future use of `Mutex` within a fatal signal handler. This method is
496*9356374aSAndroid Build Coastguard Worker   // intended for use only for last-ditch attempts to log crash information.
497*9356374aSAndroid Build Coastguard Worker   // It does not guarantee that attempts to use Mutexes within the handler will
498*9356374aSAndroid Build Coastguard Worker   // not deadlock; it merely makes other faults less likely.
499*9356374aSAndroid Build Coastguard Worker   //
500*9356374aSAndroid Build Coastguard Worker   // WARNING:  This routine must be invoked from a signal handler, and the
501*9356374aSAndroid Build Coastguard Worker   // signal handler must either loop forever or terminate the process.
502*9356374aSAndroid Build Coastguard Worker   // Attempts to return from (or `longjmp` out of) the signal handler once this
503*9356374aSAndroid Build Coastguard Worker   // call has been made may cause arbitrary program behaviour including
504*9356374aSAndroid Build Coastguard Worker   // crashes and deadlocks.
505*9356374aSAndroid Build Coastguard Worker   static void InternalAttemptToUseMutexInFatalSignalHandler();
506*9356374aSAndroid Build Coastguard Worker 
507*9356374aSAndroid Build Coastguard Worker  private:
508*9356374aSAndroid Build Coastguard Worker   std::atomic<intptr_t> mu_;  // The Mutex state.
509*9356374aSAndroid Build Coastguard Worker 
510*9356374aSAndroid Build Coastguard Worker   // Post()/Wait() versus associated PerThreadSem; in class for required
511*9356374aSAndroid Build Coastguard Worker   // friendship with PerThreadSem.
512*9356374aSAndroid Build Coastguard Worker   static void IncrementSynchSem(Mutex* mu, base_internal::PerThreadSynch* w);
513*9356374aSAndroid Build Coastguard Worker   static bool DecrementSynchSem(Mutex* mu, base_internal::PerThreadSynch* w,
514*9356374aSAndroid Build Coastguard Worker                                 synchronization_internal::KernelTimeout t);
515*9356374aSAndroid Build Coastguard Worker 
516*9356374aSAndroid Build Coastguard Worker   // slow path acquire
517*9356374aSAndroid Build Coastguard Worker   void LockSlowLoop(SynchWaitParams* waitp, int flags);
518*9356374aSAndroid Build Coastguard Worker   // wrappers around LockSlowLoop()
519*9356374aSAndroid Build Coastguard Worker   bool LockSlowWithDeadline(MuHow how, const Condition* cond,
520*9356374aSAndroid Build Coastguard Worker                             synchronization_internal::KernelTimeout t,
521*9356374aSAndroid Build Coastguard Worker                             int flags);
522*9356374aSAndroid Build Coastguard Worker   void LockSlow(MuHow how, const Condition* cond,
523*9356374aSAndroid Build Coastguard Worker                 int flags) ABSL_ATTRIBUTE_COLD;
524*9356374aSAndroid Build Coastguard Worker   // slow path release
525*9356374aSAndroid Build Coastguard Worker   void UnlockSlow(SynchWaitParams* waitp) ABSL_ATTRIBUTE_COLD;
526*9356374aSAndroid Build Coastguard Worker   // TryLock slow path.
527*9356374aSAndroid Build Coastguard Worker   bool TryLockSlow();
528*9356374aSAndroid Build Coastguard Worker   // ReaderTryLock slow path.
529*9356374aSAndroid Build Coastguard Worker   bool ReaderTryLockSlow();
530*9356374aSAndroid Build Coastguard Worker   // Common code between Await() and AwaitWithTimeout/Deadline()
531*9356374aSAndroid Build Coastguard Worker   bool AwaitCommon(const Condition& cond,
532*9356374aSAndroid Build Coastguard Worker                    synchronization_internal::KernelTimeout t);
533*9356374aSAndroid Build Coastguard Worker   bool LockWhenCommon(const Condition& cond,
534*9356374aSAndroid Build Coastguard Worker                       synchronization_internal::KernelTimeout t, bool write);
535*9356374aSAndroid Build Coastguard Worker   // Attempt to remove thread s from queue.
536*9356374aSAndroid Build Coastguard Worker   void TryRemove(base_internal::PerThreadSynch* s);
537*9356374aSAndroid Build Coastguard Worker   // Block a thread on mutex.
538*9356374aSAndroid Build Coastguard Worker   void Block(base_internal::PerThreadSynch* s);
539*9356374aSAndroid Build Coastguard Worker   // Wake a thread; return successor.
540*9356374aSAndroid Build Coastguard Worker   base_internal::PerThreadSynch* Wakeup(base_internal::PerThreadSynch* w);
541*9356374aSAndroid Build Coastguard Worker   void Dtor();
542*9356374aSAndroid Build Coastguard Worker 
543*9356374aSAndroid Build Coastguard Worker   friend class CondVar;   // for access to Trans()/Fer().
544*9356374aSAndroid Build Coastguard Worker   void Trans(MuHow how);  // used for CondVar->Mutex transfer
545*9356374aSAndroid Build Coastguard Worker   void Fer(
546*9356374aSAndroid Build Coastguard Worker       base_internal::PerThreadSynch* w);  // used for CondVar->Mutex transfer
547*9356374aSAndroid Build Coastguard Worker 
548*9356374aSAndroid Build Coastguard Worker   // Catch the error of writing Mutex when intending MutexLock.
Mutex(const volatile Mutex *)549*9356374aSAndroid Build Coastguard Worker   explicit Mutex(const volatile Mutex* /*ignored*/) {}
550*9356374aSAndroid Build Coastguard Worker 
551*9356374aSAndroid Build Coastguard Worker   Mutex(const Mutex&) = delete;
552*9356374aSAndroid Build Coastguard Worker   Mutex& operator=(const Mutex&) = delete;
553*9356374aSAndroid Build Coastguard Worker };
554*9356374aSAndroid Build Coastguard Worker 
555*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
556*9356374aSAndroid Build Coastguard Worker // Mutex RAII Wrappers
557*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
558*9356374aSAndroid Build Coastguard Worker 
559*9356374aSAndroid Build Coastguard Worker // MutexLock
560*9356374aSAndroid Build Coastguard Worker //
561*9356374aSAndroid Build Coastguard Worker // `MutexLock` is a helper class, which acquires and releases a `Mutex` via
562*9356374aSAndroid Build Coastguard Worker // RAII.
563*9356374aSAndroid Build Coastguard Worker //
564*9356374aSAndroid Build Coastguard Worker // Example:
565*9356374aSAndroid Build Coastguard Worker //
566*9356374aSAndroid Build Coastguard Worker // Class Foo {
567*9356374aSAndroid Build Coastguard Worker //  public:
568*9356374aSAndroid Build Coastguard Worker //   Foo::Bar* Baz() {
569*9356374aSAndroid Build Coastguard Worker //     MutexLock lock(&mu_);
570*9356374aSAndroid Build Coastguard Worker //     ...
571*9356374aSAndroid Build Coastguard Worker //     return bar;
572*9356374aSAndroid Build Coastguard Worker //   }
573*9356374aSAndroid Build Coastguard Worker //
574*9356374aSAndroid Build Coastguard Worker // private:
575*9356374aSAndroid Build Coastguard Worker //   Mutex mu_;
576*9356374aSAndroid Build Coastguard Worker // };
577*9356374aSAndroid Build Coastguard Worker class ABSL_SCOPED_LOCKABLE MutexLock {
578*9356374aSAndroid Build Coastguard Worker  public:
579*9356374aSAndroid Build Coastguard Worker   // Constructors
580*9356374aSAndroid Build Coastguard Worker 
581*9356374aSAndroid Build Coastguard Worker   // Calls `mu->Lock()` and returns when that call returns. That is, `*mu` is
582*9356374aSAndroid Build Coastguard Worker   // guaranteed to be locked when this object is constructed. Requires that
583*9356374aSAndroid Build Coastguard Worker   // `mu` be dereferenceable.
MutexLock(Mutex * mu)584*9356374aSAndroid Build Coastguard Worker   explicit MutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) : mu_(mu) {
585*9356374aSAndroid Build Coastguard Worker     this->mu_->Lock();
586*9356374aSAndroid Build Coastguard Worker   }
587*9356374aSAndroid Build Coastguard Worker 
588*9356374aSAndroid Build Coastguard Worker   // Like above, but calls `mu->LockWhen(cond)` instead. That is, in addition to
589*9356374aSAndroid Build Coastguard Worker   // the above, the condition given by `cond` is also guaranteed to hold when
590*9356374aSAndroid Build Coastguard Worker   // this object is constructed.
MutexLock(Mutex * mu,const Condition & cond)591*9356374aSAndroid Build Coastguard Worker   explicit MutexLock(Mutex* mu, const Condition& cond)
592*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
593*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
594*9356374aSAndroid Build Coastguard Worker     this->mu_->LockWhen(cond);
595*9356374aSAndroid Build Coastguard Worker   }
596*9356374aSAndroid Build Coastguard Worker 
597*9356374aSAndroid Build Coastguard Worker   MutexLock(const MutexLock&) = delete;  // NOLINT(runtime/mutex)
598*9356374aSAndroid Build Coastguard Worker   MutexLock(MutexLock&&) = delete;       // NOLINT(runtime/mutex)
599*9356374aSAndroid Build Coastguard Worker   MutexLock& operator=(const MutexLock&) = delete;
600*9356374aSAndroid Build Coastguard Worker   MutexLock& operator=(MutexLock&&) = delete;
601*9356374aSAndroid Build Coastguard Worker 
ABSL_UNLOCK_FUNCTION()602*9356374aSAndroid Build Coastguard Worker   ~MutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->Unlock(); }
603*9356374aSAndroid Build Coastguard Worker 
604*9356374aSAndroid Build Coastguard Worker  private:
605*9356374aSAndroid Build Coastguard Worker   Mutex* const mu_;
606*9356374aSAndroid Build Coastguard Worker };
607*9356374aSAndroid Build Coastguard Worker 
608*9356374aSAndroid Build Coastguard Worker // ReaderMutexLock
609*9356374aSAndroid Build Coastguard Worker //
610*9356374aSAndroid Build Coastguard Worker // The `ReaderMutexLock` is a helper class, like `MutexLock`, which acquires and
611*9356374aSAndroid Build Coastguard Worker // releases a shared lock on a `Mutex` via RAII.
612*9356374aSAndroid Build Coastguard Worker class ABSL_SCOPED_LOCKABLE ReaderMutexLock {
613*9356374aSAndroid Build Coastguard Worker  public:
ReaderMutexLock(Mutex * mu)614*9356374aSAndroid Build Coastguard Worker   explicit ReaderMutexLock(Mutex* mu) ABSL_SHARED_LOCK_FUNCTION(mu) : mu_(mu) {
615*9356374aSAndroid Build Coastguard Worker     mu->ReaderLock();
616*9356374aSAndroid Build Coastguard Worker   }
617*9356374aSAndroid Build Coastguard Worker 
ReaderMutexLock(Mutex * mu,const Condition & cond)618*9356374aSAndroid Build Coastguard Worker   explicit ReaderMutexLock(Mutex* mu, const Condition& cond)
619*9356374aSAndroid Build Coastguard Worker       ABSL_SHARED_LOCK_FUNCTION(mu)
620*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
621*9356374aSAndroid Build Coastguard Worker     mu->ReaderLockWhen(cond);
622*9356374aSAndroid Build Coastguard Worker   }
623*9356374aSAndroid Build Coastguard Worker 
624*9356374aSAndroid Build Coastguard Worker   ReaderMutexLock(const ReaderMutexLock&) = delete;
625*9356374aSAndroid Build Coastguard Worker   ReaderMutexLock(ReaderMutexLock&&) = delete;
626*9356374aSAndroid Build Coastguard Worker   ReaderMutexLock& operator=(const ReaderMutexLock&) = delete;
627*9356374aSAndroid Build Coastguard Worker   ReaderMutexLock& operator=(ReaderMutexLock&&) = delete;
628*9356374aSAndroid Build Coastguard Worker 
ABSL_UNLOCK_FUNCTION()629*9356374aSAndroid Build Coastguard Worker   ~ReaderMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->ReaderUnlock(); }
630*9356374aSAndroid Build Coastguard Worker 
631*9356374aSAndroid Build Coastguard Worker  private:
632*9356374aSAndroid Build Coastguard Worker   Mutex* const mu_;
633*9356374aSAndroid Build Coastguard Worker };
634*9356374aSAndroid Build Coastguard Worker 
635*9356374aSAndroid Build Coastguard Worker // WriterMutexLock
636*9356374aSAndroid Build Coastguard Worker //
637*9356374aSAndroid Build Coastguard Worker // The `WriterMutexLock` is a helper class, like `MutexLock`, which acquires and
638*9356374aSAndroid Build Coastguard Worker // releases a write (exclusive) lock on a `Mutex` via RAII.
639*9356374aSAndroid Build Coastguard Worker class ABSL_SCOPED_LOCKABLE WriterMutexLock {
640*9356374aSAndroid Build Coastguard Worker  public:
WriterMutexLock(Mutex * mu)641*9356374aSAndroid Build Coastguard Worker   explicit WriterMutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
642*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
643*9356374aSAndroid Build Coastguard Worker     mu->WriterLock();
644*9356374aSAndroid Build Coastguard Worker   }
645*9356374aSAndroid Build Coastguard Worker 
WriterMutexLock(Mutex * mu,const Condition & cond)646*9356374aSAndroid Build Coastguard Worker   explicit WriterMutexLock(Mutex* mu, const Condition& cond)
647*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
648*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
649*9356374aSAndroid Build Coastguard Worker     mu->WriterLockWhen(cond);
650*9356374aSAndroid Build Coastguard Worker   }
651*9356374aSAndroid Build Coastguard Worker 
652*9356374aSAndroid Build Coastguard Worker   WriterMutexLock(const WriterMutexLock&) = delete;
653*9356374aSAndroid Build Coastguard Worker   WriterMutexLock(WriterMutexLock&&) = delete;
654*9356374aSAndroid Build Coastguard Worker   WriterMutexLock& operator=(const WriterMutexLock&) = delete;
655*9356374aSAndroid Build Coastguard Worker   WriterMutexLock& operator=(WriterMutexLock&&) = delete;
656*9356374aSAndroid Build Coastguard Worker 
ABSL_UNLOCK_FUNCTION()657*9356374aSAndroid Build Coastguard Worker   ~WriterMutexLock() ABSL_UNLOCK_FUNCTION() { this->mu_->WriterUnlock(); }
658*9356374aSAndroid Build Coastguard Worker 
659*9356374aSAndroid Build Coastguard Worker  private:
660*9356374aSAndroid Build Coastguard Worker   Mutex* const mu_;
661*9356374aSAndroid Build Coastguard Worker };
662*9356374aSAndroid Build Coastguard Worker 
663*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
664*9356374aSAndroid Build Coastguard Worker // Condition
665*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
666*9356374aSAndroid Build Coastguard Worker //
667*9356374aSAndroid Build Coastguard Worker // `Mutex` contains a number of member functions which take a `Condition` as an
668*9356374aSAndroid Build Coastguard Worker // argument; clients can wait for conditions to become `true` before attempting
669*9356374aSAndroid Build Coastguard Worker // to acquire the mutex. These sections are known as "condition critical"
670*9356374aSAndroid Build Coastguard Worker // sections. To use a `Condition`, you simply need to construct it, and use
671*9356374aSAndroid Build Coastguard Worker // within an appropriate `Mutex` member function; everything else in the
672*9356374aSAndroid Build Coastguard Worker // `Condition` class is an implementation detail.
673*9356374aSAndroid Build Coastguard Worker //
674*9356374aSAndroid Build Coastguard Worker // A `Condition` is specified as a function pointer which returns a boolean.
675*9356374aSAndroid Build Coastguard Worker // `Condition` functions should be pure functions -- their results should depend
676*9356374aSAndroid Build Coastguard Worker // only on passed arguments, should not consult any external state (such as
677*9356374aSAndroid Build Coastguard Worker // clocks), and should have no side-effects, aside from debug logging. Any
678*9356374aSAndroid Build Coastguard Worker // objects that the function may access should be limited to those which are
679*9356374aSAndroid Build Coastguard Worker // constant while the mutex is blocked on the condition (e.g. a stack variable),
680*9356374aSAndroid Build Coastguard Worker // or objects of state protected explicitly by the mutex.
681*9356374aSAndroid Build Coastguard Worker //
682*9356374aSAndroid Build Coastguard Worker // No matter which construction is used for `Condition`, the underlying
683*9356374aSAndroid Build Coastguard Worker // function pointer / functor / callable must not throw any
684*9356374aSAndroid Build Coastguard Worker // exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in
685*9356374aSAndroid Build Coastguard Worker // the face of a throwing `Condition`. (When Abseil is allowed to depend
686*9356374aSAndroid Build Coastguard Worker // on C++17, these function pointers will be explicitly marked
687*9356374aSAndroid Build Coastguard Worker // `noexcept`; until then this requirement cannot be enforced in the
688*9356374aSAndroid Build Coastguard Worker // type system.)
689*9356374aSAndroid Build Coastguard Worker //
690*9356374aSAndroid Build Coastguard Worker // Note: to use a `Condition`, you need only construct it and pass it to a
691*9356374aSAndroid Build Coastguard Worker // suitable `Mutex' member function, such as `Mutex::Await()`, or to the
692*9356374aSAndroid Build Coastguard Worker // constructor of one of the scope guard classes.
693*9356374aSAndroid Build Coastguard Worker //
694*9356374aSAndroid Build Coastguard Worker // Example using LockWhen/Unlock:
695*9356374aSAndroid Build Coastguard Worker //
696*9356374aSAndroid Build Coastguard Worker //   // assume count_ is not internal reference count
697*9356374aSAndroid Build Coastguard Worker //   int count_ ABSL_GUARDED_BY(mu_);
698*9356374aSAndroid Build Coastguard Worker //   Condition count_is_zero(+[](int *count) { return *count == 0; }, &count_);
699*9356374aSAndroid Build Coastguard Worker //
700*9356374aSAndroid Build Coastguard Worker //   mu_.LockWhen(count_is_zero);
701*9356374aSAndroid Build Coastguard Worker //   // ...
702*9356374aSAndroid Build Coastguard Worker //   mu_.Unlock();
703*9356374aSAndroid Build Coastguard Worker //
704*9356374aSAndroid Build Coastguard Worker // Example using a scope guard:
705*9356374aSAndroid Build Coastguard Worker //
706*9356374aSAndroid Build Coastguard Worker //   {
707*9356374aSAndroid Build Coastguard Worker //     MutexLock lock(&mu_, count_is_zero);
708*9356374aSAndroid Build Coastguard Worker //     // ...
709*9356374aSAndroid Build Coastguard Worker //   }
710*9356374aSAndroid Build Coastguard Worker //
711*9356374aSAndroid Build Coastguard Worker // When multiple threads are waiting on exactly the same condition, make sure
712*9356374aSAndroid Build Coastguard Worker // that they are constructed with the same parameters (same pointer to function
713*9356374aSAndroid Build Coastguard Worker // + arg, or same pointer to object + method), so that the mutex implementation
714*9356374aSAndroid Build Coastguard Worker // can avoid redundantly evaluating the same condition for each thread.
715*9356374aSAndroid Build Coastguard Worker class Condition {
716*9356374aSAndroid Build Coastguard Worker  public:
717*9356374aSAndroid Build Coastguard Worker   // A Condition that returns the result of "(*func)(arg)"
718*9356374aSAndroid Build Coastguard Worker   Condition(bool (*func)(void*), void* arg);
719*9356374aSAndroid Build Coastguard Worker 
720*9356374aSAndroid Build Coastguard Worker   // Templated version for people who are averse to casts.
721*9356374aSAndroid Build Coastguard Worker   //
722*9356374aSAndroid Build Coastguard Worker   // To use a lambda, prepend it with unary plus, which converts the lambda
723*9356374aSAndroid Build Coastguard Worker   // into a function pointer:
724*9356374aSAndroid Build Coastguard Worker   //     Condition(+[](T* t) { return ...; }, arg).
725*9356374aSAndroid Build Coastguard Worker   //
726*9356374aSAndroid Build Coastguard Worker   // Note: lambdas in this case must contain no bound variables.
727*9356374aSAndroid Build Coastguard Worker   //
728*9356374aSAndroid Build Coastguard Worker   // See class comment for performance advice.
729*9356374aSAndroid Build Coastguard Worker   template <typename T>
730*9356374aSAndroid Build Coastguard Worker   Condition(bool (*func)(T*), T* arg);
731*9356374aSAndroid Build Coastguard Worker 
732*9356374aSAndroid Build Coastguard Worker   // Same as above, but allows for cases where `arg` comes from a pointer that
733*9356374aSAndroid Build Coastguard Worker   // is convertible to the function parameter type `T*` but not an exact match.
734*9356374aSAndroid Build Coastguard Worker   //
735*9356374aSAndroid Build Coastguard Worker   // For example, the argument might be `X*` but the function takes `const X*`,
736*9356374aSAndroid Build Coastguard Worker   // or the argument might be `Derived*` while the function takes `Base*`, and
737*9356374aSAndroid Build Coastguard Worker   // so on for cases where the argument pointer can be implicitly converted.
738*9356374aSAndroid Build Coastguard Worker   //
739*9356374aSAndroid Build Coastguard Worker   // Implementation notes: This constructor overload is required in addition to
740*9356374aSAndroid Build Coastguard Worker   // the one above to allow deduction of `T` from `arg` for cases such as where
741*9356374aSAndroid Build Coastguard Worker   // a function template is passed as `func`. Also, the dummy `typename = void`
742*9356374aSAndroid Build Coastguard Worker   // template parameter exists just to work around a MSVC mangling bug.
743*9356374aSAndroid Build Coastguard Worker   template <typename T, typename = void>
744*9356374aSAndroid Build Coastguard Worker   Condition(bool (*func)(T*),
745*9356374aSAndroid Build Coastguard Worker             typename absl::internal::type_identity<T>::type* arg);
746*9356374aSAndroid Build Coastguard Worker 
747*9356374aSAndroid Build Coastguard Worker   // Templated version for invoking a method that returns a `bool`.
748*9356374aSAndroid Build Coastguard Worker   //
749*9356374aSAndroid Build Coastguard Worker   // `Condition(object, &Class::Method)` constructs a `Condition` that evaluates
750*9356374aSAndroid Build Coastguard Worker   // `object->Method()`.
751*9356374aSAndroid Build Coastguard Worker   //
752*9356374aSAndroid Build Coastguard Worker   // Implementation Note: `absl::internal::type_identity` is used to allow
753*9356374aSAndroid Build Coastguard Worker   // methods to come from base classes. A simpler signature like
754*9356374aSAndroid Build Coastguard Worker   // `Condition(T*, bool (T::*)())` does not suffice.
755*9356374aSAndroid Build Coastguard Worker   template <typename T>
756*9356374aSAndroid Build Coastguard Worker   Condition(T* object,
757*9356374aSAndroid Build Coastguard Worker             bool (absl::internal::type_identity<T>::type::*method)());
758*9356374aSAndroid Build Coastguard Worker 
759*9356374aSAndroid Build Coastguard Worker   // Same as above, for const members
760*9356374aSAndroid Build Coastguard Worker   template <typename T>
761*9356374aSAndroid Build Coastguard Worker   Condition(const T* object,
762*9356374aSAndroid Build Coastguard Worker             bool (absl::internal::type_identity<T>::type::*method)() const);
763*9356374aSAndroid Build Coastguard Worker 
764*9356374aSAndroid Build Coastguard Worker   // A Condition that returns the value of `*cond`
765*9356374aSAndroid Build Coastguard Worker   explicit Condition(const bool* cond);
766*9356374aSAndroid Build Coastguard Worker 
767*9356374aSAndroid Build Coastguard Worker   // Templated version for invoking a functor that returns a `bool`.
768*9356374aSAndroid Build Coastguard Worker   // This approach accepts pointers to non-mutable lambdas, `std::function`,
769*9356374aSAndroid Build Coastguard Worker   // the result of` std::bind` and user-defined functors that define
770*9356374aSAndroid Build Coastguard Worker   // `bool F::operator()() const`.
771*9356374aSAndroid Build Coastguard Worker   //
772*9356374aSAndroid Build Coastguard Worker   // Example:
773*9356374aSAndroid Build Coastguard Worker   //
774*9356374aSAndroid Build Coastguard Worker   //   auto reached = [this, current]() {
775*9356374aSAndroid Build Coastguard Worker   //     mu_.AssertReaderHeld();                // For annotalysis.
776*9356374aSAndroid Build Coastguard Worker   //     return processed_ >= current;
777*9356374aSAndroid Build Coastguard Worker   //   };
778*9356374aSAndroid Build Coastguard Worker   //   mu_.Await(Condition(&reached));
779*9356374aSAndroid Build Coastguard Worker   //
780*9356374aSAndroid Build Coastguard Worker   // NOTE: never use "mu_.AssertHeld()" instead of "mu_.AssertReaderHeld()" in
781*9356374aSAndroid Build Coastguard Worker   // the lambda as it may be called when the mutex is being unlocked from a
782*9356374aSAndroid Build Coastguard Worker   // scope holding only a reader lock, which will make the assertion not
783*9356374aSAndroid Build Coastguard Worker   // fulfilled and crash the binary.
784*9356374aSAndroid Build Coastguard Worker 
785*9356374aSAndroid Build Coastguard Worker   // See class comment for performance advice. In particular, if there
786*9356374aSAndroid Build Coastguard Worker   // might be more than one waiter for the same condition, make sure
787*9356374aSAndroid Build Coastguard Worker   // that all waiters construct the condition with the same pointers.
788*9356374aSAndroid Build Coastguard Worker 
789*9356374aSAndroid Build Coastguard Worker   // Implementation note: The second template parameter ensures that this
790*9356374aSAndroid Build Coastguard Worker   // constructor doesn't participate in overload resolution if T doesn't have
791*9356374aSAndroid Build Coastguard Worker   // `bool operator() const`.
792*9356374aSAndroid Build Coastguard Worker   template <typename T, typename E = decltype(static_cast<bool (T::*)() const>(
793*9356374aSAndroid Build Coastguard Worker                             &T::operator()))>
Condition(const T * obj)794*9356374aSAndroid Build Coastguard Worker   explicit Condition(const T* obj)
795*9356374aSAndroid Build Coastguard Worker       : Condition(obj, static_cast<bool (T::*)() const>(&T::operator())) {}
796*9356374aSAndroid Build Coastguard Worker 
797*9356374aSAndroid Build Coastguard Worker   // A Condition that always returns `true`.
798*9356374aSAndroid Build Coastguard Worker   // kTrue is only useful in a narrow set of circumstances, mostly when
799*9356374aSAndroid Build Coastguard Worker   // it's passed conditionally. For example:
800*9356374aSAndroid Build Coastguard Worker   //
801*9356374aSAndroid Build Coastguard Worker   //   mu.LockWhen(some_flag ? kTrue : SomeOtherCondition);
802*9356374aSAndroid Build Coastguard Worker   //
803*9356374aSAndroid Build Coastguard Worker   // Note: {LockWhen,Await}With{Deadline,Timeout} methods with kTrue condition
804*9356374aSAndroid Build Coastguard Worker   // don't return immediately when the timeout happens, they still block until
805*9356374aSAndroid Build Coastguard Worker   // the Mutex becomes available. The return value of these methods does
806*9356374aSAndroid Build Coastguard Worker   // not indicate if the timeout was reached; rather it indicates whether or
807*9356374aSAndroid Build Coastguard Worker   // not the condition is true.
808*9356374aSAndroid Build Coastguard Worker   ABSL_CONST_INIT static const Condition kTrue;
809*9356374aSAndroid Build Coastguard Worker 
810*9356374aSAndroid Build Coastguard Worker   // Evaluates the condition.
811*9356374aSAndroid Build Coastguard Worker   bool Eval() const;
812*9356374aSAndroid Build Coastguard Worker 
813*9356374aSAndroid Build Coastguard Worker   // Returns `true` if the two conditions are guaranteed to return the same
814*9356374aSAndroid Build Coastguard Worker   // value if evaluated at the same time, `false` if the evaluation *may* return
815*9356374aSAndroid Build Coastguard Worker   // different results.
816*9356374aSAndroid Build Coastguard Worker   //
817*9356374aSAndroid Build Coastguard Worker   // Two `Condition` values are guaranteed equal if both their `func` and `arg`
818*9356374aSAndroid Build Coastguard Worker   // components are the same. A null pointer is equivalent to a `true`
819*9356374aSAndroid Build Coastguard Worker   // condition.
820*9356374aSAndroid Build Coastguard Worker   static bool GuaranteedEqual(const Condition* a, const Condition* b);
821*9356374aSAndroid Build Coastguard Worker 
822*9356374aSAndroid Build Coastguard Worker  private:
823*9356374aSAndroid Build Coastguard Worker   // Sizing an allocation for a method pointer can be subtle. In the Itanium
824*9356374aSAndroid Build Coastguard Worker   // specifications, a method pointer has a predictable, uniform size. On the
825*9356374aSAndroid Build Coastguard Worker   // other hand, MSVC ABI, method pointer sizes vary based on the
826*9356374aSAndroid Build Coastguard Worker   // inheritance of the class. Specifically, method pointers from classes with
827*9356374aSAndroid Build Coastguard Worker   // multiple inheritance are bigger than those of classes with single
828*9356374aSAndroid Build Coastguard Worker   // inheritance. Other variations also exist.
829*9356374aSAndroid Build Coastguard Worker 
830*9356374aSAndroid Build Coastguard Worker #ifndef _MSC_VER
831*9356374aSAndroid Build Coastguard Worker   // Allocation for a function pointer or method pointer.
832*9356374aSAndroid Build Coastguard Worker   // The {0} initializer ensures that all unused bytes of this buffer are
833*9356374aSAndroid Build Coastguard Worker   // always zeroed out.  This is necessary, because GuaranteedEqual() compares
834*9356374aSAndroid Build Coastguard Worker   // all of the bytes, unaware of which bytes are relevant to a given `eval_`.
835*9356374aSAndroid Build Coastguard Worker   using MethodPtr = bool (Condition::*)();
836*9356374aSAndroid Build Coastguard Worker   char callback_[sizeof(MethodPtr)] = {0};
837*9356374aSAndroid Build Coastguard Worker #else
838*9356374aSAndroid Build Coastguard Worker   // It is well known that the larget MSVC pointer-to-member is 24 bytes. This
839*9356374aSAndroid Build Coastguard Worker   // may be the largest known pointer-to-member of any platform. For this
840*9356374aSAndroid Build Coastguard Worker   // reason we will allocate 24 bytes for MSVC platform toolchains.
841*9356374aSAndroid Build Coastguard Worker   char callback_[24] = {0};
842*9356374aSAndroid Build Coastguard Worker #endif
843*9356374aSAndroid Build Coastguard Worker 
844*9356374aSAndroid Build Coastguard Worker   // Function with which to evaluate callbacks and/or arguments.
845*9356374aSAndroid Build Coastguard Worker   bool (*eval_)(const Condition*) = nullptr;
846*9356374aSAndroid Build Coastguard Worker 
847*9356374aSAndroid Build Coastguard Worker   // Either an argument for a function call or an object for a method call.
848*9356374aSAndroid Build Coastguard Worker   void* arg_ = nullptr;
849*9356374aSAndroid Build Coastguard Worker 
850*9356374aSAndroid Build Coastguard Worker   // Various functions eval_ can point to:
851*9356374aSAndroid Build Coastguard Worker   static bool CallVoidPtrFunction(const Condition*);
852*9356374aSAndroid Build Coastguard Worker   template <typename T>
853*9356374aSAndroid Build Coastguard Worker   static bool CastAndCallFunction(const Condition* c);
854*9356374aSAndroid Build Coastguard Worker   template <typename T, typename ConditionMethodPtr>
855*9356374aSAndroid Build Coastguard Worker   static bool CastAndCallMethod(const Condition* c);
856*9356374aSAndroid Build Coastguard Worker 
857*9356374aSAndroid Build Coastguard Worker   // Helper methods for storing, validating, and reading callback arguments.
858*9356374aSAndroid Build Coastguard Worker   template <typename T>
StoreCallback(T callback)859*9356374aSAndroid Build Coastguard Worker   inline void StoreCallback(T callback) {
860*9356374aSAndroid Build Coastguard Worker     static_assert(
861*9356374aSAndroid Build Coastguard Worker         sizeof(callback) <= sizeof(callback_),
862*9356374aSAndroid Build Coastguard Worker         "An overlarge pointer was passed as a callback to Condition.");
863*9356374aSAndroid Build Coastguard Worker     std::memcpy(callback_, &callback, sizeof(callback));
864*9356374aSAndroid Build Coastguard Worker   }
865*9356374aSAndroid Build Coastguard Worker 
866*9356374aSAndroid Build Coastguard Worker   template <typename T>
ReadCallback(T * callback)867*9356374aSAndroid Build Coastguard Worker   inline void ReadCallback(T* callback) const {
868*9356374aSAndroid Build Coastguard Worker     std::memcpy(callback, callback_, sizeof(*callback));
869*9356374aSAndroid Build Coastguard Worker   }
870*9356374aSAndroid Build Coastguard Worker 
AlwaysTrue(const Condition *)871*9356374aSAndroid Build Coastguard Worker   static bool AlwaysTrue(const Condition*) { return true; }
872*9356374aSAndroid Build Coastguard Worker 
873*9356374aSAndroid Build Coastguard Worker   // Used only to create kTrue.
Condition()874*9356374aSAndroid Build Coastguard Worker   constexpr Condition() : eval_(AlwaysTrue), arg_(nullptr) {}
875*9356374aSAndroid Build Coastguard Worker };
876*9356374aSAndroid Build Coastguard Worker 
877*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
878*9356374aSAndroid Build Coastguard Worker // CondVar
879*9356374aSAndroid Build Coastguard Worker // -----------------------------------------------------------------------------
880*9356374aSAndroid Build Coastguard Worker //
881*9356374aSAndroid Build Coastguard Worker // A condition variable, reflecting state evaluated separately outside of the
882*9356374aSAndroid Build Coastguard Worker // `Mutex` object, which can be signaled to wake callers.
883*9356374aSAndroid Build Coastguard Worker // This class is not normally needed; use `Mutex` member functions such as
884*9356374aSAndroid Build Coastguard Worker // `Mutex::Await()` and intrinsic `Condition` abstractions. In rare cases
885*9356374aSAndroid Build Coastguard Worker // with many threads and many conditions, `CondVar` may be faster.
886*9356374aSAndroid Build Coastguard Worker //
887*9356374aSAndroid Build Coastguard Worker // The implementation may deliver signals to any condition variable at
888*9356374aSAndroid Build Coastguard Worker // any time, even when no call to `Signal()` or `SignalAll()` is made; as a
889*9356374aSAndroid Build Coastguard Worker // result, upon being awoken, you must check the logical condition you have
890*9356374aSAndroid Build Coastguard Worker // been waiting upon.
891*9356374aSAndroid Build Coastguard Worker //
892*9356374aSAndroid Build Coastguard Worker // Examples:
893*9356374aSAndroid Build Coastguard Worker //
894*9356374aSAndroid Build Coastguard Worker // Usage for a thread waiting for some condition C protected by mutex mu:
895*9356374aSAndroid Build Coastguard Worker //       mu.Lock();
896*9356374aSAndroid Build Coastguard Worker //       while (!C) { cv->Wait(&mu); }        // releases and reacquires mu
897*9356374aSAndroid Build Coastguard Worker //       //  C holds; process data
898*9356374aSAndroid Build Coastguard Worker //       mu.Unlock();
899*9356374aSAndroid Build Coastguard Worker //
900*9356374aSAndroid Build Coastguard Worker // Usage to wake T is:
901*9356374aSAndroid Build Coastguard Worker //       mu.Lock();
902*9356374aSAndroid Build Coastguard Worker //       // process data, possibly establishing C
903*9356374aSAndroid Build Coastguard Worker //       if (C) { cv->Signal(); }
904*9356374aSAndroid Build Coastguard Worker //       mu.Unlock();
905*9356374aSAndroid Build Coastguard Worker //
906*9356374aSAndroid Build Coastguard Worker // If C may be useful to more than one waiter, use `SignalAll()` instead of
907*9356374aSAndroid Build Coastguard Worker // `Signal()`.
908*9356374aSAndroid Build Coastguard Worker //
909*9356374aSAndroid Build Coastguard Worker // With this implementation it is efficient to use `Signal()/SignalAll()` inside
910*9356374aSAndroid Build Coastguard Worker // the locked region; this usage can make reasoning about your program easier.
911*9356374aSAndroid Build Coastguard Worker //
912*9356374aSAndroid Build Coastguard Worker class CondVar {
913*9356374aSAndroid Build Coastguard Worker  public:
914*9356374aSAndroid Build Coastguard Worker   // A `CondVar` allocated on the heap or on the stack can use the this
915*9356374aSAndroid Build Coastguard Worker   // constructor.
916*9356374aSAndroid Build Coastguard Worker   CondVar();
917*9356374aSAndroid Build Coastguard Worker 
918*9356374aSAndroid Build Coastguard Worker   // CondVar::Wait()
919*9356374aSAndroid Build Coastguard Worker   //
920*9356374aSAndroid Build Coastguard Worker   // Atomically releases a `Mutex` and blocks on this condition variable.
921*9356374aSAndroid Build Coastguard Worker   // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
922*9356374aSAndroid Build Coastguard Worker   // spurious wakeup), then reacquires the `Mutex` and returns.
923*9356374aSAndroid Build Coastguard Worker   //
924*9356374aSAndroid Build Coastguard Worker   // Requires and ensures that the current thread holds the `Mutex`.
Wait(Mutex * mu)925*9356374aSAndroid Build Coastguard Worker   void Wait(Mutex* mu) {
926*9356374aSAndroid Build Coastguard Worker     WaitCommon(mu, synchronization_internal::KernelTimeout::Never());
927*9356374aSAndroid Build Coastguard Worker   }
928*9356374aSAndroid Build Coastguard Worker 
929*9356374aSAndroid Build Coastguard Worker   // CondVar::WaitWithTimeout()
930*9356374aSAndroid Build Coastguard Worker   //
931*9356374aSAndroid Build Coastguard Worker   // Atomically releases a `Mutex` and blocks on this condition variable.
932*9356374aSAndroid Build Coastguard Worker   // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
933*9356374aSAndroid Build Coastguard Worker   // spurious wakeup), or until the timeout has expired, then reacquires
934*9356374aSAndroid Build Coastguard Worker   // the `Mutex` and returns.
935*9356374aSAndroid Build Coastguard Worker   //
936*9356374aSAndroid Build Coastguard Worker   // Returns true if the timeout has expired without this `CondVar`
937*9356374aSAndroid Build Coastguard Worker   // being signalled in any manner. If both the timeout has expired
938*9356374aSAndroid Build Coastguard Worker   // and this `CondVar` has been signalled, the implementation is free
939*9356374aSAndroid Build Coastguard Worker   // to return `true` or `false`.
940*9356374aSAndroid Build Coastguard Worker   //
941*9356374aSAndroid Build Coastguard Worker   // Requires and ensures that the current thread holds the `Mutex`.
WaitWithTimeout(Mutex * mu,absl::Duration timeout)942*9356374aSAndroid Build Coastguard Worker   bool WaitWithTimeout(Mutex* mu, absl::Duration timeout) {
943*9356374aSAndroid Build Coastguard Worker     return WaitCommon(mu, synchronization_internal::KernelTimeout(timeout));
944*9356374aSAndroid Build Coastguard Worker   }
945*9356374aSAndroid Build Coastguard Worker 
946*9356374aSAndroid Build Coastguard Worker   // CondVar::WaitWithDeadline()
947*9356374aSAndroid Build Coastguard Worker   //
948*9356374aSAndroid Build Coastguard Worker   // Atomically releases a `Mutex` and blocks on this condition variable.
949*9356374aSAndroid Build Coastguard Worker   // Waits until awakened by a call to `Signal()` or `SignalAll()` (or a
950*9356374aSAndroid Build Coastguard Worker   // spurious wakeup), or until the deadline has passed, then reacquires
951*9356374aSAndroid Build Coastguard Worker   // the `Mutex` and returns.
952*9356374aSAndroid Build Coastguard Worker   //
953*9356374aSAndroid Build Coastguard Worker   // Deadlines in the past are equivalent to an immediate deadline.
954*9356374aSAndroid Build Coastguard Worker   //
955*9356374aSAndroid Build Coastguard Worker   // Returns true if the deadline has passed without this `CondVar`
956*9356374aSAndroid Build Coastguard Worker   // being signalled in any manner. If both the deadline has passed
957*9356374aSAndroid Build Coastguard Worker   // and this `CondVar` has been signalled, the implementation is free
958*9356374aSAndroid Build Coastguard Worker   // to return `true` or `false`.
959*9356374aSAndroid Build Coastguard Worker   //
960*9356374aSAndroid Build Coastguard Worker   // Requires and ensures that the current thread holds the `Mutex`.
WaitWithDeadline(Mutex * mu,absl::Time deadline)961*9356374aSAndroid Build Coastguard Worker   bool WaitWithDeadline(Mutex* mu, absl::Time deadline) {
962*9356374aSAndroid Build Coastguard Worker     return WaitCommon(mu, synchronization_internal::KernelTimeout(deadline));
963*9356374aSAndroid Build Coastguard Worker   }
964*9356374aSAndroid Build Coastguard Worker 
965*9356374aSAndroid Build Coastguard Worker   // CondVar::Signal()
966*9356374aSAndroid Build Coastguard Worker   //
967*9356374aSAndroid Build Coastguard Worker   // Signal this `CondVar`; wake at least one waiter if one exists.
968*9356374aSAndroid Build Coastguard Worker   void Signal();
969*9356374aSAndroid Build Coastguard Worker 
970*9356374aSAndroid Build Coastguard Worker   // CondVar::SignalAll()
971*9356374aSAndroid Build Coastguard Worker   //
972*9356374aSAndroid Build Coastguard Worker   // Signal this `CondVar`; wake all waiters.
973*9356374aSAndroid Build Coastguard Worker   void SignalAll();
974*9356374aSAndroid Build Coastguard Worker 
975*9356374aSAndroid Build Coastguard Worker   // CondVar::EnableDebugLog()
976*9356374aSAndroid Build Coastguard Worker   //
977*9356374aSAndroid Build Coastguard Worker   // Causes all subsequent uses of this `CondVar` to be logged via
978*9356374aSAndroid Build Coastguard Worker   // `ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if `name != 0`.
979*9356374aSAndroid Build Coastguard Worker   // Note: this method substantially reduces `CondVar` performance.
980*9356374aSAndroid Build Coastguard Worker   void EnableDebugLog(const char* name);
981*9356374aSAndroid Build Coastguard Worker 
982*9356374aSAndroid Build Coastguard Worker  private:
983*9356374aSAndroid Build Coastguard Worker   bool WaitCommon(Mutex* mutex, synchronization_internal::KernelTimeout t);
984*9356374aSAndroid Build Coastguard Worker   void Remove(base_internal::PerThreadSynch* s);
985*9356374aSAndroid Build Coastguard Worker   std::atomic<intptr_t> cv_;  // Condition variable state.
986*9356374aSAndroid Build Coastguard Worker   CondVar(const CondVar&) = delete;
987*9356374aSAndroid Build Coastguard Worker   CondVar& operator=(const CondVar&) = delete;
988*9356374aSAndroid Build Coastguard Worker };
989*9356374aSAndroid Build Coastguard Worker 
990*9356374aSAndroid Build Coastguard Worker // Variants of MutexLock.
991*9356374aSAndroid Build Coastguard Worker //
992*9356374aSAndroid Build Coastguard Worker // If you find yourself using one of these, consider instead using
993*9356374aSAndroid Build Coastguard Worker // Mutex::Unlock() and/or if-statements for clarity.
994*9356374aSAndroid Build Coastguard Worker 
995*9356374aSAndroid Build Coastguard Worker // MutexLockMaybe
996*9356374aSAndroid Build Coastguard Worker //
997*9356374aSAndroid Build Coastguard Worker // MutexLockMaybe is like MutexLock, but is a no-op when mu is null.
998*9356374aSAndroid Build Coastguard Worker class ABSL_SCOPED_LOCKABLE MutexLockMaybe {
999*9356374aSAndroid Build Coastguard Worker  public:
MutexLockMaybe(Mutex * mu)1000*9356374aSAndroid Build Coastguard Worker   explicit MutexLockMaybe(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
1001*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
1002*9356374aSAndroid Build Coastguard Worker     if (this->mu_ != nullptr) {
1003*9356374aSAndroid Build Coastguard Worker       this->mu_->Lock();
1004*9356374aSAndroid Build Coastguard Worker     }
1005*9356374aSAndroid Build Coastguard Worker   }
1006*9356374aSAndroid Build Coastguard Worker 
MutexLockMaybe(Mutex * mu,const Condition & cond)1007*9356374aSAndroid Build Coastguard Worker   explicit MutexLockMaybe(Mutex* mu, const Condition& cond)
1008*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
1009*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
1010*9356374aSAndroid Build Coastguard Worker     if (this->mu_ != nullptr) {
1011*9356374aSAndroid Build Coastguard Worker       this->mu_->LockWhen(cond);
1012*9356374aSAndroid Build Coastguard Worker     }
1013*9356374aSAndroid Build Coastguard Worker   }
1014*9356374aSAndroid Build Coastguard Worker 
ABSL_UNLOCK_FUNCTION()1015*9356374aSAndroid Build Coastguard Worker   ~MutexLockMaybe() ABSL_UNLOCK_FUNCTION() {
1016*9356374aSAndroid Build Coastguard Worker     if (this->mu_ != nullptr) {
1017*9356374aSAndroid Build Coastguard Worker       this->mu_->Unlock();
1018*9356374aSAndroid Build Coastguard Worker     }
1019*9356374aSAndroid Build Coastguard Worker   }
1020*9356374aSAndroid Build Coastguard Worker 
1021*9356374aSAndroid Build Coastguard Worker  private:
1022*9356374aSAndroid Build Coastguard Worker   Mutex* const mu_;
1023*9356374aSAndroid Build Coastguard Worker   MutexLockMaybe(const MutexLockMaybe&) = delete;
1024*9356374aSAndroid Build Coastguard Worker   MutexLockMaybe(MutexLockMaybe&&) = delete;
1025*9356374aSAndroid Build Coastguard Worker   MutexLockMaybe& operator=(const MutexLockMaybe&) = delete;
1026*9356374aSAndroid Build Coastguard Worker   MutexLockMaybe& operator=(MutexLockMaybe&&) = delete;
1027*9356374aSAndroid Build Coastguard Worker };
1028*9356374aSAndroid Build Coastguard Worker 
1029*9356374aSAndroid Build Coastguard Worker // ReleasableMutexLock
1030*9356374aSAndroid Build Coastguard Worker //
1031*9356374aSAndroid Build Coastguard Worker // ReleasableMutexLock is like MutexLock, but permits `Release()` of its
1032*9356374aSAndroid Build Coastguard Worker // mutex before destruction. `Release()` may be called at most once.
1033*9356374aSAndroid Build Coastguard Worker class ABSL_SCOPED_LOCKABLE ReleasableMutexLock {
1034*9356374aSAndroid Build Coastguard Worker  public:
ReleasableMutexLock(Mutex * mu)1035*9356374aSAndroid Build Coastguard Worker   explicit ReleasableMutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
1036*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
1037*9356374aSAndroid Build Coastguard Worker     this->mu_->Lock();
1038*9356374aSAndroid Build Coastguard Worker   }
1039*9356374aSAndroid Build Coastguard Worker 
ReleasableMutexLock(Mutex * mu,const Condition & cond)1040*9356374aSAndroid Build Coastguard Worker   explicit ReleasableMutexLock(Mutex* mu, const Condition& cond)
1041*9356374aSAndroid Build Coastguard Worker       ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)
1042*9356374aSAndroid Build Coastguard Worker       : mu_(mu) {
1043*9356374aSAndroid Build Coastguard Worker     this->mu_->LockWhen(cond);
1044*9356374aSAndroid Build Coastguard Worker   }
1045*9356374aSAndroid Build Coastguard Worker 
ABSL_UNLOCK_FUNCTION()1046*9356374aSAndroid Build Coastguard Worker   ~ReleasableMutexLock() ABSL_UNLOCK_FUNCTION() {
1047*9356374aSAndroid Build Coastguard Worker     if (this->mu_ != nullptr) {
1048*9356374aSAndroid Build Coastguard Worker       this->mu_->Unlock();
1049*9356374aSAndroid Build Coastguard Worker     }
1050*9356374aSAndroid Build Coastguard Worker   }
1051*9356374aSAndroid Build Coastguard Worker 
1052*9356374aSAndroid Build Coastguard Worker   void Release() ABSL_UNLOCK_FUNCTION();
1053*9356374aSAndroid Build Coastguard Worker 
1054*9356374aSAndroid Build Coastguard Worker  private:
1055*9356374aSAndroid Build Coastguard Worker   Mutex* mu_;
1056*9356374aSAndroid Build Coastguard Worker   ReleasableMutexLock(const ReleasableMutexLock&) = delete;
1057*9356374aSAndroid Build Coastguard Worker   ReleasableMutexLock(ReleasableMutexLock&&) = delete;
1058*9356374aSAndroid Build Coastguard Worker   ReleasableMutexLock& operator=(const ReleasableMutexLock&) = delete;
1059*9356374aSAndroid Build Coastguard Worker   ReleasableMutexLock& operator=(ReleasableMutexLock&&) = delete;
1060*9356374aSAndroid Build Coastguard Worker };
1061*9356374aSAndroid Build Coastguard Worker 
Mutex()1062*9356374aSAndroid Build Coastguard Worker inline Mutex::Mutex() : mu_(0) {
1063*9356374aSAndroid Build Coastguard Worker   ABSL_TSAN_MUTEX_CREATE(this, __tsan_mutex_not_static);
1064*9356374aSAndroid Build Coastguard Worker }
1065*9356374aSAndroid Build Coastguard Worker 
Mutex(absl::ConstInitType)1066*9356374aSAndroid Build Coastguard Worker inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {}
1067*9356374aSAndroid Build Coastguard Worker 
1068*9356374aSAndroid Build Coastguard Worker #if !defined(__APPLE__) && !defined(ABSL_BUILD_DLL)
1069*9356374aSAndroid Build Coastguard Worker ABSL_ATTRIBUTE_ALWAYS_INLINE
~Mutex()1070*9356374aSAndroid Build Coastguard Worker inline Mutex::~Mutex() { Dtor(); }
1071*9356374aSAndroid Build Coastguard Worker #endif
1072*9356374aSAndroid Build Coastguard Worker 
1073*9356374aSAndroid Build Coastguard Worker #if defined(NDEBUG) && !defined(ABSL_HAVE_THREAD_SANITIZER)
1074*9356374aSAndroid Build Coastguard Worker // Use default (empty) destructor in release build for performance reasons.
1075*9356374aSAndroid Build Coastguard Worker // We need to mark both Dtor and ~Mutex as always inline for inconsistent
1076*9356374aSAndroid Build Coastguard Worker // builds that use both NDEBUG and !NDEBUG with dynamic libraries. In these
1077*9356374aSAndroid Build Coastguard Worker // cases we want the empty functions to dissolve entirely rather than being
1078*9356374aSAndroid Build Coastguard Worker // exported from dynamic libraries and potentially override the non-empty ones.
1079*9356374aSAndroid Build Coastguard Worker ABSL_ATTRIBUTE_ALWAYS_INLINE
Dtor()1080*9356374aSAndroid Build Coastguard Worker inline void Mutex::Dtor() {}
1081*9356374aSAndroid Build Coastguard Worker #endif
1082*9356374aSAndroid Build Coastguard Worker 
CondVar()1083*9356374aSAndroid Build Coastguard Worker inline CondVar::CondVar() : cv_(0) {}
1084*9356374aSAndroid Build Coastguard Worker 
1085*9356374aSAndroid Build Coastguard Worker // static
1086*9356374aSAndroid Build Coastguard Worker template <typename T, typename ConditionMethodPtr>
CastAndCallMethod(const Condition * c)1087*9356374aSAndroid Build Coastguard Worker bool Condition::CastAndCallMethod(const Condition* c) {
1088*9356374aSAndroid Build Coastguard Worker   T* object = static_cast<T*>(c->arg_);
1089*9356374aSAndroid Build Coastguard Worker   ConditionMethodPtr condition_method_pointer;
1090*9356374aSAndroid Build Coastguard Worker   c->ReadCallback(&condition_method_pointer);
1091*9356374aSAndroid Build Coastguard Worker   return (object->*condition_method_pointer)();
1092*9356374aSAndroid Build Coastguard Worker }
1093*9356374aSAndroid Build Coastguard Worker 
1094*9356374aSAndroid Build Coastguard Worker // static
1095*9356374aSAndroid Build Coastguard Worker template <typename T>
CastAndCallFunction(const Condition * c)1096*9356374aSAndroid Build Coastguard Worker bool Condition::CastAndCallFunction(const Condition* c) {
1097*9356374aSAndroid Build Coastguard Worker   bool (*function)(T*);
1098*9356374aSAndroid Build Coastguard Worker   c->ReadCallback(&function);
1099*9356374aSAndroid Build Coastguard Worker   T* argument = static_cast<T*>(c->arg_);
1100*9356374aSAndroid Build Coastguard Worker   return (*function)(argument);
1101*9356374aSAndroid Build Coastguard Worker }
1102*9356374aSAndroid Build Coastguard Worker 
1103*9356374aSAndroid Build Coastguard Worker template <typename T>
Condition(bool (* func)(T *),T * arg)1104*9356374aSAndroid Build Coastguard Worker inline Condition::Condition(bool (*func)(T*), T* arg)
1105*9356374aSAndroid Build Coastguard Worker     : eval_(&CastAndCallFunction<T>),
1106*9356374aSAndroid Build Coastguard Worker       arg_(const_cast<void*>(static_cast<const void*>(arg))) {
1107*9356374aSAndroid Build Coastguard Worker   static_assert(sizeof(&func) <= sizeof(callback_),
1108*9356374aSAndroid Build Coastguard Worker                 "An overlarge function pointer was passed to Condition.");
1109*9356374aSAndroid Build Coastguard Worker   StoreCallback(func);
1110*9356374aSAndroid Build Coastguard Worker }
1111*9356374aSAndroid Build Coastguard Worker 
1112*9356374aSAndroid Build Coastguard Worker template <typename T, typename>
Condition(bool (* func)(T *),typename absl::internal::type_identity<T>::type * arg)1113*9356374aSAndroid Build Coastguard Worker inline Condition::Condition(
1114*9356374aSAndroid Build Coastguard Worker     bool (*func)(T*), typename absl::internal::type_identity<T>::type* arg)
1115*9356374aSAndroid Build Coastguard Worker     // Just delegate to the overload above.
1116*9356374aSAndroid Build Coastguard Worker     : Condition(func, arg) {}
1117*9356374aSAndroid Build Coastguard Worker 
1118*9356374aSAndroid Build Coastguard Worker template <typename T>
Condition(T * object,bool (absl::internal::type_identity<T>::type::* method)())1119*9356374aSAndroid Build Coastguard Worker inline Condition::Condition(
1120*9356374aSAndroid Build Coastguard Worker     T* object, bool (absl::internal::type_identity<T>::type::*method)())
1121*9356374aSAndroid Build Coastguard Worker     : eval_(&CastAndCallMethod<T, decltype(method)>), arg_(object) {
1122*9356374aSAndroid Build Coastguard Worker   static_assert(sizeof(&method) <= sizeof(callback_),
1123*9356374aSAndroid Build Coastguard Worker                 "An overlarge method pointer was passed to Condition.");
1124*9356374aSAndroid Build Coastguard Worker   StoreCallback(method);
1125*9356374aSAndroid Build Coastguard Worker }
1126*9356374aSAndroid Build Coastguard Worker 
1127*9356374aSAndroid Build Coastguard Worker template <typename T>
Condition(const T * object,bool (absl::internal::type_identity<T>::type::* method)()const)1128*9356374aSAndroid Build Coastguard Worker inline Condition::Condition(
1129*9356374aSAndroid Build Coastguard Worker     const T* object,
1130*9356374aSAndroid Build Coastguard Worker     bool (absl::internal::type_identity<T>::type::*method)() const)
1131*9356374aSAndroid Build Coastguard Worker     : eval_(&CastAndCallMethod<const T, decltype(method)>),
1132*9356374aSAndroid Build Coastguard Worker       arg_(reinterpret_cast<void*>(const_cast<T*>(object))) {
1133*9356374aSAndroid Build Coastguard Worker   StoreCallback(method);
1134*9356374aSAndroid Build Coastguard Worker }
1135*9356374aSAndroid Build Coastguard Worker 
1136*9356374aSAndroid Build Coastguard Worker // Register hooks for profiling support.
1137*9356374aSAndroid Build Coastguard Worker //
1138*9356374aSAndroid Build Coastguard Worker // The function pointer registered here will be called whenever a mutex is
1139*9356374aSAndroid Build Coastguard Worker // contended.  The callback is given the cycles for which waiting happened (as
1140*9356374aSAndroid Build Coastguard Worker // measured by //absl/base/internal/cycleclock.h, and which may not
1141*9356374aSAndroid Build Coastguard Worker // be real "cycle" counts.)
1142*9356374aSAndroid Build Coastguard Worker //
1143*9356374aSAndroid Build Coastguard Worker // There is no ordering guarantee between when the hook is registered and when
1144*9356374aSAndroid Build Coastguard Worker // callbacks will begin.  Only a single profiler can be installed in a running
1145*9356374aSAndroid Build Coastguard Worker // binary; if this function is called a second time with a different function
1146*9356374aSAndroid Build Coastguard Worker // pointer, the value is ignored (and will cause an assertion failure in debug
1147*9356374aSAndroid Build Coastguard Worker // mode.)
1148*9356374aSAndroid Build Coastguard Worker void RegisterMutexProfiler(void (*fn)(int64_t wait_cycles));
1149*9356374aSAndroid Build Coastguard Worker 
1150*9356374aSAndroid Build Coastguard Worker // Register a hook for Mutex tracing.
1151*9356374aSAndroid Build Coastguard Worker //
1152*9356374aSAndroid Build Coastguard Worker // The function pointer registered here will be called whenever a mutex is
1153*9356374aSAndroid Build Coastguard Worker // contended.  The callback is given an opaque handle to the contended mutex,
1154*9356374aSAndroid Build Coastguard Worker // an event name, and the number of wait cycles (as measured by
1155*9356374aSAndroid Build Coastguard Worker // //absl/base/internal/cycleclock.h, and which may not be real
1156*9356374aSAndroid Build Coastguard Worker // "cycle" counts.)
1157*9356374aSAndroid Build Coastguard Worker //
1158*9356374aSAndroid Build Coastguard Worker // The only event name currently sent is "slow release".
1159*9356374aSAndroid Build Coastguard Worker //
1160*9356374aSAndroid Build Coastguard Worker // This has the same ordering and single-use limitations as
1161*9356374aSAndroid Build Coastguard Worker // RegisterMutexProfiler() above.
1162*9356374aSAndroid Build Coastguard Worker void RegisterMutexTracer(void (*fn)(const char* msg, const void* obj,
1163*9356374aSAndroid Build Coastguard Worker                                     int64_t wait_cycles));
1164*9356374aSAndroid Build Coastguard Worker 
1165*9356374aSAndroid Build Coastguard Worker // Register a hook for CondVar tracing.
1166*9356374aSAndroid Build Coastguard Worker //
1167*9356374aSAndroid Build Coastguard Worker // The function pointer registered here will be called here on various CondVar
1168*9356374aSAndroid Build Coastguard Worker // events.  The callback is given an opaque handle to the CondVar object and
1169*9356374aSAndroid Build Coastguard Worker // a string identifying the event.  This is thread-safe, but only a single
1170*9356374aSAndroid Build Coastguard Worker // tracer can be registered.
1171*9356374aSAndroid Build Coastguard Worker //
1172*9356374aSAndroid Build Coastguard Worker // Events that can be sent are "Wait", "Unwait", "Signal wakeup", and
1173*9356374aSAndroid Build Coastguard Worker // "SignalAll wakeup".
1174*9356374aSAndroid Build Coastguard Worker //
1175*9356374aSAndroid Build Coastguard Worker // This has the same ordering and single-use limitations as
1176*9356374aSAndroid Build Coastguard Worker // RegisterMutexProfiler() above.
1177*9356374aSAndroid Build Coastguard Worker void RegisterCondVarTracer(void (*fn)(const char* msg, const void* cv));
1178*9356374aSAndroid Build Coastguard Worker 
1179*9356374aSAndroid Build Coastguard Worker // EnableMutexInvariantDebugging()
1180*9356374aSAndroid Build Coastguard Worker //
1181*9356374aSAndroid Build Coastguard Worker // Enable or disable global support for Mutex invariant debugging.  If enabled,
1182*9356374aSAndroid Build Coastguard Worker // then invariant predicates can be registered per-Mutex for debug checking.
1183*9356374aSAndroid Build Coastguard Worker // See Mutex::EnableInvariantDebugging().
1184*9356374aSAndroid Build Coastguard Worker void EnableMutexInvariantDebugging(bool enabled);
1185*9356374aSAndroid Build Coastguard Worker 
1186*9356374aSAndroid Build Coastguard Worker // When in debug mode, and when the feature has been enabled globally, the
1187*9356374aSAndroid Build Coastguard Worker // implementation will keep track of lock ordering and complain (or optionally
1188*9356374aSAndroid Build Coastguard Worker // crash) if a cycle is detected in the acquired-before graph.
1189*9356374aSAndroid Build Coastguard Worker 
1190*9356374aSAndroid Build Coastguard Worker // Possible modes of operation for the deadlock detector in debug mode.
1191*9356374aSAndroid Build Coastguard Worker enum class OnDeadlockCycle {
1192*9356374aSAndroid Build Coastguard Worker   kIgnore,  // Neither report on nor attempt to track cycles in lock ordering
1193*9356374aSAndroid Build Coastguard Worker   kReport,  // Report lock cycles to stderr when detected
1194*9356374aSAndroid Build Coastguard Worker   kAbort,   // Report lock cycles to stderr when detected, then abort
1195*9356374aSAndroid Build Coastguard Worker };
1196*9356374aSAndroid Build Coastguard Worker 
1197*9356374aSAndroid Build Coastguard Worker // SetMutexDeadlockDetectionMode()
1198*9356374aSAndroid Build Coastguard Worker //
1199*9356374aSAndroid Build Coastguard Worker // Enable or disable global support for detection of potential deadlocks
1200*9356374aSAndroid Build Coastguard Worker // due to Mutex lock ordering inversions.  When set to 'kIgnore', tracking of
1201*9356374aSAndroid Build Coastguard Worker // lock ordering is disabled.  Otherwise, in debug builds, a lock ordering graph
1202*9356374aSAndroid Build Coastguard Worker // will be maintained internally, and detected cycles will be reported in
1203*9356374aSAndroid Build Coastguard Worker // the manner chosen here.
1204*9356374aSAndroid Build Coastguard Worker void SetMutexDeadlockDetectionMode(OnDeadlockCycle mode);
1205*9356374aSAndroid Build Coastguard Worker 
1206*9356374aSAndroid Build Coastguard Worker ABSL_NAMESPACE_END
1207*9356374aSAndroid Build Coastguard Worker }  // namespace absl
1208*9356374aSAndroid Build Coastguard Worker 
1209*9356374aSAndroid Build Coastguard Worker // In some build configurations we pass --detect-odr-violations to the
1210*9356374aSAndroid Build Coastguard Worker // gold linker.  This causes it to flag weak symbol overrides as ODR
1211*9356374aSAndroid Build Coastguard Worker // violations.  Because ODR only applies to C++ and not C,
1212*9356374aSAndroid Build Coastguard Worker // --detect-odr-violations ignores symbols not mangled with C++ names.
1213*9356374aSAndroid Build Coastguard Worker // By changing our extension points to be extern "C", we dodge this
1214*9356374aSAndroid Build Coastguard Worker // check.
1215*9356374aSAndroid Build Coastguard Worker extern "C" {
1216*9356374aSAndroid Build Coastguard Worker void ABSL_INTERNAL_C_SYMBOL(AbslInternalMutexYield)();
1217*9356374aSAndroid Build Coastguard Worker }  // extern "C"
1218*9356374aSAndroid Build Coastguard Worker 
1219*9356374aSAndroid Build Coastguard Worker #endif  // ABSL_SYNCHRONIZATION_MUTEX_H_
1220