Lines Matching full:mutex
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
86 // Mutex
89 // A `Mutex` is a non-reentrant (aka non-recursive) Mutually Exclusive lock
94 // A `Mutex` has two basic operations: `Mutex::Lock()` and `Mutex::Unlock()`.
95 // The `Lock()` operation *acquires* a `Mutex` (in a state known as an
97 // Mutex. During the span of time between the Lock() and Unlock() operations,
98 // a mutex is said to be *held*. By design, all mutexes support exclusive/write
99 // locks, as this is the most common way to use a mutex.
101 // Mutex operations are only allowed under certain conditions; otherwise an
103 // both the current state of the mutex and the identity of the threads that
106 // The `Mutex` state machine for basic lock/unlock operations is quite simple:
115 // * Calls to `Unlock()` require that the mutex be held, and must be made in the
117 // acquired the mutex; otherwise the call is invalid.
119 // * The mutex being non-reentrant (or non-recursive) means that a call to
121 // mutex; such a call is invalid.
125 // the mutex is held *by a particular thread*.
127 // An "invalid" operation has undefined behavior. The `Mutex` implementation
133 // `Mutex` is not guaranteed to be "fair" in prioritizing waiting threads; it
149 // See also `MutexLock`, below, for scoped `Mutex` acquisition.
151 class ABSL_LOCKABLE ABSL_ATTRIBUTE_WARN_UNUSED Mutex {
153 // Creates a `Mutex` that is not held by anyone. This constructor is
156 // To create `Mutex` instances with static storage duration
158 // `Mutex::Mutex(absl::kConstInit)` below instead.
159 Mutex();
161 // Creates a mutex with static storage duration. A global variable
170 // ABSL_CONST_INIT absl::Mutex mu(absl::kConstInit);
172 explicit constexpr Mutex(absl::ConstInitType);
174 ~Mutex();
176 // Mutex::Lock()
178 // Blocks the calling thread, if necessary, until this `Mutex` is free, and
182 // Mutex::Unlock()
184 // Releases this `Mutex` and returns it from the exclusive/write state to the
185 // free state. Calling thread must hold the `Mutex` exclusively.
188 // Mutex::TryLock()
190 // If the mutex can be acquired without blocking, does so exclusively and
192 // probability if the `Mutex` was free.
195 // Mutex::AssertHeld()
197 // Require that the mutex be held exclusively (write mode) by this thread.
199 // If the mutex is not currently held by this thread, this function may report
209 // A Mutex can also be used as a starvation-free reader-writer lock.
213 // The Mutex API provides `Writer*()` aliases for the existing `Lock()`,
218 // Introducing reader locks necessarily complicates the `Mutex` state
220 // of a mutex in such cases. Note that ReaderLock() may block even if the lock
237 // Mutex::ReaderLock()
239 // Blocks the calling thread, if necessary, until this `Mutex` is either free,
242 // on the mutex.
246 // Mutex::ReaderUnlock()
248 // Releases a read share of this `Mutex`. `ReaderUnlock` may return a mutex to
249 // the free state if this thread holds the last reader lock on the mutex. Note
250 // that you cannot call `ReaderUnlock()` on a mutex held in write mode.
253 // Mutex::ReaderTryLock()
255 // If the mutex can be acquired without blocking, acquires this mutex for
257 // `true` with high probability if the `Mutex` was free or shared.
260 // Mutex::AssertReaderHeld()
262 // Require that the mutex be held at least in shared mode (read mode) by this
265 // If the mutex is not currently held by this thread, this function may report
271 // Mutex::WriterLock()
272 // Mutex::WriterUnlock()
273 // Mutex::WriterTryLock()
275 // Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.
278 // methods) to distinguish simple exclusive `Mutex` usage (`Lock()`,
293 // Conditional usage of a `Mutex` can occur using two distinct paradigms:
295 // * Use of `Mutex` member functions with `Condition` objects.
298 // In general, prefer use of `Condition` and the `Mutex` member functions
303 // `Mutex` contains member functions for performing lock operations only under
306 // the `Mutex`. The condition must be invariant w.r.t. environmental state
308 // always be invoked with the mutex held in at least read mode, so you should
321 // Mutex::Await()
323 // Unlocks this `Mutex` and blocks until simultaneously both `cond` is `true`
324 // and this `Mutex` can be reacquired, then reacquires this `Mutex` in the
328 // `Await()` requires that this thread holds this `Mutex` in some mode.
333 // Mutex::LockWhen()
334 // Mutex::ReaderLockWhen()
335 // Mutex::WriterLockWhen()
337 // Blocks until simultaneously both `cond` is `true` and this `Mutex` can
338 // be acquired, then atomically acquires this `Mutex`. `LockWhen()` is
356 // Mutex Variants with Timeouts/Deadlines
359 // Mutex::AwaitWithTimeout()
360 // Mutex::AwaitWithDeadline()
362 // Unlocks this `Mutex` and blocks until simultaneously:
365 // - this `Mutex` can be reacquired,
366 // then reacquire this `Mutex` in the same mode in which it was previously
375 // This method requires that this thread holds this `Mutex` in some mode.
384 // Mutex::LockWhenWithTimeout()
385 // Mutex::ReaderLockWhenWithTimeout()
386 // Mutex::WriterLockWhenWithTimeout()
390 // - this `Mutex` can be acquired,
391 // then atomically acquires this `Mutex`, returning `true` iff `cond` is
410 // Mutex::LockWhenWithDeadline()
411 // Mutex::ReaderLockWhenWithDeadline()
412 // Mutex::WriterLockWhenWithDeadline()
416 // - this `Mutex` can be acquired,
417 // then atomically acquires this Mutex, returning `true` iff `cond` is `true`
440 // Mutex::EnableInvariantDebugging()
444 // this `Mutex` should hold (for example: just after acquire, just before
450 // substantially reduce `Mutex` performance; it should be set only for
455 // Mutex::EnableDebugLog()
457 // Cause all subsequent uses of this `Mutex` to be logged via
461 // Note: This method substantially reduces `Mutex` performance.
466 // Mutex::ForgetDeadlockInfo()
469 // about this `Mutex`. Call this method in debug mode when the lock ordering
470 // of a `Mutex` changes.
473 // Mutex::AssertNotHeld()
475 // Return immediately if this thread does not hold this `Mutex` in any
492 // Mutex::InternalAttemptToUseMutexInFatalSignalHandler()
494 // Causes the `Mutex` implementation to prepare itself for re-entry caused by
495 // future use of `Mutex` within a fatal signal handler. This method is
508 std::atomic<intptr_t> mu_; // The Mutex state.
512 static void IncrementSynchSem(Mutex* mu, base_internal::PerThreadSynch* w);
513 static bool DecrementSynchSem(Mutex* mu, base_internal::PerThreadSynch* w,
537 // Block a thread on mutex.
544 void Trans(MuHow how); // used for CondVar->Mutex transfer
546 base_internal::PerThreadSynch* w); // used for CondVar->Mutex transfer
548 // Catch the error of writing Mutex when intending MutexLock.
549 explicit Mutex(const volatile Mutex* /*ignored*/) {} in Mutex() function
551 Mutex(const Mutex&) = delete;
552 Mutex& operator=(const Mutex&) = delete;
556 // Mutex RAII Wrappers
561 // `MutexLock` is a helper class, which acquires and releases a `Mutex` via
575 // Mutex mu_;
584 explicit MutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) : mu_(mu) { in MutexLock()
591 explicit MutexLock(Mutex* mu, const Condition& cond) in MutexLock()
597 MutexLock(const MutexLock&) = delete; // NOLINT(runtime/mutex)
598 MutexLock(MutexLock&&) = delete; // NOLINT(runtime/mutex)
605 Mutex* const mu_;
611 // releases a shared lock on a `Mutex` via RAII.
614 explicit ReaderMutexLock(Mutex* mu) ABSL_SHARED_LOCK_FUNCTION(mu) : mu_(mu) { in ReaderMutexLock()
618 explicit ReaderMutexLock(Mutex* mu, const Condition& cond) in ReaderMutexLock()
632 Mutex* const mu_;
638 // releases a write (exclusive) lock on a `Mutex` via RAII.
641 explicit WriterMutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) in WriterMutexLock()
646 explicit WriterMutexLock(Mutex* mu, const Condition& cond) in WriterMutexLock()
660 Mutex* const mu_;
667 // `Mutex` contains a number of member functions which take a `Condition` as an
669 // to acquire the mutex. These sections are known as "condition critical"
671 // within an appropriate `Mutex` member function; everything else in the
679 // constant while the mutex is blocked on the condition (e.g. a stack variable),
680 // or objects of state protected explicitly by the mutex.
684 // exceptions. Correctness of `Mutex` / `Condition` is not guaranteed in
691 // suitable `Mutex' member function, such as `Mutex::Await()`, or to the
713 // + arg, or same pointer to object + method), so that the mutex implementation
781 // the lambda as it may be called when the mutex is being unlocked from a
805 // the Mutex becomes available. The return value of these methods does
882 // `Mutex` object, which can be signaled to wake callers.
883 // This class is not normally needed; use `Mutex` member functions such as
884 // `Mutex::Await()` and intrinsic `Condition` abstractions. In rare cases
894 // Usage for a thread waiting for some condition C protected by mutex mu:
920 // Atomically releases a `Mutex` and blocks on this condition variable.
922 // spurious wakeup), then reacquires the `Mutex` and returns.
924 // Requires and ensures that the current thread holds the `Mutex`.
925 void Wait(Mutex* mu) { in Wait()
931 // Atomically releases a `Mutex` and blocks on this condition variable.
934 // the `Mutex` and returns.
941 // Requires and ensures that the current thread holds the `Mutex`.
942 bool WaitWithTimeout(Mutex* mu, absl::Duration timeout) { in WaitWithTimeout()
948 // Atomically releases a `Mutex` and blocks on this condition variable.
951 // the `Mutex` and returns.
960 // Requires and ensures that the current thread holds the `Mutex`.
961 bool WaitWithDeadline(Mutex* mu, absl::Time deadline) { in WaitWithDeadline()
983 bool WaitCommon(Mutex* mutex, synchronization_internal::KernelTimeout t);
993 // Mutex::Unlock() and/or if-statements for clarity.
1000 explicit MutexLockMaybe(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) in MutexLockMaybe()
1007 explicit MutexLockMaybe(Mutex* mu, const Condition& cond) in MutexLockMaybe()
1022 Mutex* const mu_;
1032 // mutex before destruction. `Release()` may be called at most once.
1035 explicit ReleasableMutexLock(Mutex* mu) ABSL_EXCLUSIVE_LOCK_FUNCTION(mu) in ReleasableMutexLock()
1040 explicit ReleasableMutexLock(Mutex* mu, const Condition& cond) in ReleasableMutexLock()
1055 Mutex* mu_;
1062 inline Mutex::Mutex() : mu_(0) { in Mutex() function
1066 inline constexpr Mutex::Mutex(absl::ConstInitType) : mu_(0) {} in Mutex() function
1070 inline Mutex::~Mutex() { Dtor(); } in ~Mutex()
1075 // We need to mark both Dtor and ~Mutex as always inline for inconsistent
1080 inline void Mutex::Dtor() {} in Dtor()
1138 // The function pointer registered here will be called whenever a mutex is
1150 // Register a hook for Mutex tracing.
1152 // The function pointer registered here will be called whenever a mutex is
1153 // contended. The callback is given an opaque handle to the contended mutex,
1181 // Enable or disable global support for Mutex invariant debugging. If enabled,
1182 // then invariant predicates can be registered per-Mutex for debug checking.
1183 // See Mutex::EnableInvariantDebugging().
1200 // due to Mutex lock ordering inversions. When set to 'kIgnore', tracking of