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

source code of include/absl/synchronization/mutex.h