16 // mutex.h
19 // This header file defines a `Mutex` -- a mutually exclusive lock -- and the
21 // shared resources. A mutex is used to prevent multiple threads from accessing
24 // Unlike a `std::mutex`, the Abseil `Mutex` provides the following additional
26 //   * Conditional predicates intrinsic to the `Mutex` object
32 //  MutexLock - An RAII wrapper to acquire and release a `Mutex` for exclusive/
36 //            - An RAII wrapper to acquire and release a `Mutex` for shared/read
43 // In addition to simple mutex locks, this file also defines ways to perform
47 //              depends on state protected by the `Mutex` to become true.
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
83 // Mutex
86 // A `Mutex` is a non-reentrant (aka non-recursive) Mutually Exclusive lock
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
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.
98 // The `Mutex` state machine for basic lock/unlock operations is quite simple:
108 // An "invalid" operation is disallowed by the API. The `Mutex` implementation
114 // `Mutex` is not guaranteed to be "fair" in prioritizing waiting threads; it
129 // See also `MutexLock`, below, for scoped `Mutex` acquisition.
131 class ABSL_LOCKABLE Mutex {
133   // Creates a `Mutex` that is not held by anyone. This constructor is
136   // To create `Mutex` instances with static storage duration
138   // `Mutex::Mutex(absl::kConstInit)` below instead.
139   Mutex();
141   // Creates a mutex with static storage duration.  A global variable
150   //   ABSL_CONST_INIT absl::Mutex mu(absl::kConstInit);
152   explicit constexpr Mutex(absl::ConstInitType);
154   ~Mutex();
156   // Mutex::Lock()
158   // Blocks the calling thread, if necessary, until this `Mutex` is free, and
162   // Mutex::Unlock()
164   // Releases this `Mutex` and returns it from the exclusive/write state to the
165   // free state. Calling thread must hold the `Mutex` exclusively.
168   // Mutex::TryLock()
170   // If the mutex can be acquired without blocking, does so exclusively and
172   // probability if the `Mutex` was free.
175   // Mutex::AssertHeld()
177   // Require that the mutex be held exclusively (write mode) by this thread.
179   // If the mutex is not currently held by this thread, this function may report
189   // A Mutex can also be used as a starvation-free reader-writer lock.
193   // The Mutex API provides `Writer*()` aliases for the existing `Lock()`,
198   // Introducing reader locks necessarily complicates the `Mutex` state
200   // of a mutex in such cases. Note that ReaderLock() may block even if the lock
217   // Mutex::ReaderLock()
219   // Blocks the calling thread, if necessary, until this `Mutex` is either free,
222   // on the mutex.
226   // Mutex::ReaderUnlock()
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.
233   // Mutex::ReaderTryLock()
235   // If the mutex can be acquired without blocking, acquires this mutex for
237   // `true` with high probability if the `Mutex` was free or shared.
240   // Mutex::AssertReaderHeld()
242   // Require that the mutex be held at least in shared mode (read mode) by this
245   // If the mutex is not currently held by this thread, this function may report
251   // Mutex::WriterLock()
252   // Mutex::WriterUnlock()
253   // Mutex::WriterTryLock()
255   // Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.
258   // methods) to distingish simple exclusive `Mutex` usage (`Lock()`,
272   // Conditional usage of a `Mutex` can occur using two distinct paradigms:
274   //   * Use of `Mutex` member functions with `Condition` objects.
277   // In general, prefer use of `Condition` and the `Mutex` member functions
282   // `Mutex` contains member functions for performing lock operations only under
285   // the `Mutex`. The condition must be invariant w.r.t. environmental state
287   // always be invoked with the mutex held in at least read mode, so you should
300   // Mutex::Await()
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
307   // `Await()` requires that this thread holds this `Mutex` in some mode.
310   // Mutex::LockWhen()
311   // Mutex::ReaderLockWhen()
312   // Mutex::WriterLockWhen()
314   // Blocks until simultaneously both `cond` is `true` and this `Mutex` can
315   // be acquired, then atomically acquires this `Mutex`. `LockWhen()` is
327   // Mutex Variants with Timeouts/Deadlines
330   // Mutex::AwaitWithTimeout()
331   // Mutex::AwaitWithDeadline()
333   // Unlocks this `Mutex` and blocks until simultaneously:
336   //   - this `Mutex` can be reacquired,
337   // then reacquire this `Mutex` in the same mode in which it was previously
346   // This method requires that this thread holds this `Mutex` in some mode.
351   // Mutex::LockWhenWithTimeout()
352   // Mutex::ReaderLockWhenWithTimeout()
353   // Mutex::WriterLockWhenWithTimeout()
357   //   - this `Mutex` can be acquired,
358   // then atomically acquires this `Mutex`, returning `true` iff `cond` is
371   // Mutex::LockWhenWithDeadline()
372   // Mutex::ReaderLockWhenWithDeadline()
373   // Mutex::WriterLockWhenWithDeadline()
377   //   - this `Mutex` can be acquired,
378   // then atomically acquires this Mutex, returning `true` iff `cond` is `true`
395   // Mutex::EnableInvariantDebugging()
399   // this `Mutex` should hold (for example: just after acquire, just before
405   // substantially reduce `Mutex` performance; it should be set only for
410   // Mutex::EnableDebugLog()
412   // Cause all subsequent uses of this `Mutex` to be logged via
416   // Note: This method substantially reduces `Mutex` performance.
421   // Mutex::ForgetDeadlockInfo()
424   // about this `Mutex`. Call this method in debug mode when the lock ordering
425   // of a `Mutex` changes.
428   // Mutex::AssertNotHeld()
430   // Return immediately if this thread does not hold this `Mutex` in any
447   // Mutex::InternalAttemptToUseMutexInFatalSignalHandler()
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
463   std::atomic<intptr_t> mu_;  // The Mutex state.
467   static void IncrementSynchSem(Mutex *mu, base_internal::PerThreadSynch *w);
468   static bool DecrementSynchSem(Mutex *mu, base_internal::PerThreadSynch *w,
486   // Block a thread on mutex.
492   void Trans(MuHow how);  // used for CondVar->Mutex transfer
494       base_internal::PerThreadSynch *w);  // used for CondVar->Mutex transfer
496   // Catch the error of writing Mutex when intending MutexLock.
497   Mutex(const volatile Mutex * /*ignored*/) {}  // NOLINT(runtime/explicit)  in Mutex()  function
499   Mutex(const Mutex&) = delete;
500   Mutex& operator=(const Mutex&) = delete;
504 // Mutex RAII Wrappers
509 // `MutexLock` is a helper class, which acquires and releases a `Mutex` via
523 //   Mutex mu_;
532   explicit MutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) : mu_(mu) {  in MutexLock()
539   explicit MutexLock(Mutex *mu, const Condition &cond)  in MutexLock()
545   MutexLock(const MutexLock &) = delete;  // NOLINT(runtime/mutex)
546   MutexLock(MutexLock&&) = delete;  // NOLINT(runtime/mutex)
553   Mutex *const mu_;
559 // releases a shared lock on a `Mutex` via RAII.
562   explicit ReaderMutexLock(Mutex *mu) ABSL_SHARED_LOCK_FUNCTION(mu) : mu_(mu) {  in ReaderMutexLock()
566   explicit ReaderMutexLock(Mutex *mu, const Condition &cond)  in ReaderMutexLock()
580   Mutex *const mu_;
586 // releases a write (exclusive) lock on a `Mutex` via RAII.
589   explicit WriterMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)  in WriterMutexLock()
594   explicit WriterMutexLock(Mutex *mu, const Condition &cond)  in WriterMutexLock()
608   Mutex *const mu_;
615 // As noted above, `Mutex` contains a number of member functions which take a
617 // before attempting to acquire the mutex. These sections are known as
619 // construct it, and use within an appropriate `Mutex` member function;
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.
632 // exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in
639 // suitable `Mutex' member function, such as `Mutex::Await()`, or to the
661 // + arg, or same pointer to object + method), so that the mutex implementation
713   // the lambda as it may be called when the mutex is being unlocked from a
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
780 // Usage for a thread waiting for some condition C protected by mutex mu:
807   // Atomically releases a `Mutex` and blocks on this condition variable.
809   // spurious wakeup), then reacquires the `Mutex` and returns.
811   // Requires and ensures that the current thread holds the `Mutex`.
812   void Wait(Mutex *mu);
816   // Atomically releases a `Mutex` and blocks on this condition variable.
819   // the `Mutex` and returns.
826   // Requires and ensures that the current thread holds the `Mutex`.
827   bool WaitWithTimeout(Mutex *mu, absl::Duration timeout);
831   // Atomically releases a `Mutex` and blocks on this condition variable.
834   // the `Mutex` and returns.
843   // Requires and ensures that the current thread holds the `Mutex`.
844   bool WaitWithDeadline(Mutex *mu, absl::Time deadline);
864   bool WaitCommon(Mutex *mutex, synchronization_internal::KernelTimeout t);
876 // Mutex::Unlock() and/or if-statements for clarity.
883   explicit MutexLockMaybe(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)  in MutexLockMaybe()
890   explicit MutexLockMaybe(Mutex *mu, const Condition &cond)  in MutexLockMaybe()
903   Mutex *const mu_;
913 // mutex before destruction. `Release()` may be called at most once.
916   explicit ReleasableMutexLock(Mutex *mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu)  in ReleasableMutexLock()
921   explicit ReleasableMutexLock(Mutex *mu, const Condition &cond)  in ReleasableMutexLock()
934   Mutex *mu_;
941 inline Mutex::Mutex() : mu_(0) {  in Mutex()  function
945 inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {}  in Mutex()  function
993 // The function pointer registered here will be called whenever a mutex is
1004 // Register a hook for Mutex tracing.
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,
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().
1071 // due to Mutex lock ordering inversions.  When set to 'kIgnore', tracking of