class Mutex

Mutex::AssertHeld()

Require that the mutex be held exclusively (write mode) by this thread.

If the mutex is not currently held by this thread, this function may report

an error (typically by crashing with a diagnostic) or it may do nothing.

This function is intended only as a tool to assist debugging; it doesn't

guarantee correctness.

Mutex::AssertReaderHeld()

Require that the mutex be held at least in shared mode (read mode) by this

thread.

If the mutex is not currently held by this thread, this function may report

an error (typically by crashing with a diagnostic) or it may do nothing.

This function is intended only as a tool to assist debugging; it doesn't

guarantee correctness.

Mutex::EnableInvariantDebugging()

If `invariant`!=null and if invariant debugging has been enabled globally,

cause `(*invariant)(arg)` to be called at moments when the invariant for

this `Mutex` should hold (for example: just after acquire, just before

release).

The routine `invariant` should have no side-effects since it is not

guaranteed how many times it will be called; it should check the invariant

and crash if it does not hold. Enabling global invariant debugging may

substantially reduce `Mutex` performance; it should be set only for

non-production runs. Optimization options may also disable invariant

checks.

Mutex::EnableDebugLog()

Cause all subsequent uses of this `Mutex` to be logged via

`ABSL_RAW_LOG(INFO)`. Log entries are tagged with `name` if no previous

call to `EnableInvariantDebugging()` or `EnableDebugLog()` has been made.

Note: This method substantially reduces `Mutex` performance.

Mutex::ForgetDeadlockInfo()

Forget any deadlock-detection information previously gathered

about this `Mutex`. Call this method in debug mode when the lock ordering

of a `Mutex` changes.

Mutex::AssertNotHeld()

Return immediately if this thread does not hold this `Mutex` in any

mode; otherwise, may report an error (typically by crashing with a

diagnostic), or may return immediately.

Currently this check is performed only if all of:

- in debug mode

- SetMutexDeadlockDetectionMode() has been set to kReport or kAbort

- number of locks concurrently held by this thread is not large.

are true.

Mutex::InternalAttemptToUseMutexInFatalSignalHandler()

Causes the `Mutex` implementation to prepare itself for re-entry caused by

future use of `Mutex` within a fatal signal handler. This method is

intended for use only for last-ditch attempts to log crash information.

It does not guarantee that attempts to use Mutexes within the handler will

not deadlock; it merely makes other faults less likely.

WARNING: This routine must be invoked from a signal handler, and the

signal handler must either loop forever or terminate the process.

Attempts to return from (or `longjmp` out of) the signal handler once this

call has been made may cause arbitrary program behaviour including

crashes and deadlocks.

Mutex::WriterLock()

Mutex::WriterUnlock()

Mutex::WriterTryLock()

Aliases for `Mutex::Lock()`, `Mutex::Unlock()`, and `Mutex::TryLock()`.

These methods may be used (along with the complementary `Reader*()`

methods) to distinguish simple exclusive `Mutex` usage (`Lock()`,

etc.) from reader/writer lock usage.

Mutex::Await()

Unlocks this `Mutex` and blocks until simultaneously both `cond` is `true`

and this `Mutex` can be reacquired, then reacquires this `Mutex` in the

same mode in which it was previously held. If the condition is initially

`true`, `Await()` *may* skip the release/re-acquire step.

`Await()` requires that this thread holds this `Mutex` in some mode.

Mutex::LockWhen()

Mutex::ReaderLockWhen()

Mutex::WriterLockWhen()

Blocks until simultaneously both `cond` is `true` and this `Mutex` can

be acquired, then atomically acquires this `Mutex`. `LockWhen()` is

logically equivalent to `*Lock(); Await();` though they may have different

performance characteristics.

Mutex::AwaitWithTimeout()

Mutex::AwaitWithDeadline()

Unlocks this `Mutex` and blocks until simultaneously:

- either `cond` is true or the {timeout has expired, deadline has passed}

and

- this `Mutex` can be reacquired,

then reacquire this `Mutex` in the same mode in which it was previously

held, returning `true` iff `cond` is `true` on return.

If the condition is initially `true`, the implementation *may* skip the

release/re-acquire step and return immediately.

Deadlines in the past are equivalent to an immediate deadline.

Negative timeouts are equivalent to a zero timeout.

This method requires that this thread holds this `Mutex` in some mode.

Mutex::LockWhenWithTimeout()

Mutex::ReaderLockWhenWithTimeout()

Mutex::WriterLockWhenWithTimeout()

Blocks until simultaneously both:

- either `cond` is `true` or the timeout has expired, and

- this `Mutex` can be acquired,

then atomically acquires this `Mutex`, returning `true` iff `cond` is

`true` on return.

Negative timeouts are equivalent to a zero timeout.

Mutex::LockWhenWithDeadline()

Mutex::ReaderLockWhenWithDeadline()

Mutex::WriterLockWhenWithDeadline()

Blocks until simultaneously both:

- either `cond` is `true` or the deadline has been passed, and

- this `Mutex` can be acquired,

then atomically acquires this Mutex, returning `true` iff `cond` is `true`

on return.

Deadlines in the past are equivalent to an immediate deadline.

Creates a `Mutex` that is not held by anyone. This constructor is

typically used for Mutexes allocated on the heap or the stack.

To create `Mutex` instances with static storage duration

(e.g. a namespace-scoped or global variable), see

`Mutex::Mutex(absl::kConstInit)` below instead.

Creates a mutex with static storage duration. A global variable

constructed this way avoids the lifetime issues that can occur on program

startup and shutdown. (See absl/base/const_init.h.)

For Mutexes allocated on the heap and stack, instead use the default

constructor, which can interact more fully with the thread sanitizer.

Example usage:

namespace foo {

ABSL_CONST_INIT absl::Mutex mu(absl::kConstInit);

}

Mutex::lock()

Blocks the calling thread, if necessary, until this `Mutex` is free, and

then acquires it exclusively. (This lock is also known as a "write lock.")

Mutex::unlock()

Releases this `Mutex` and returns it from the exclusive/write state to the

free state. Calling thread must hold the `Mutex` exclusively.

Mutex::try_lock()

If the mutex can be acquired without blocking, does so exclusively and

returns `true`. Otherwise, returns `false`. Returns `true` with high

probability if the `Mutex` was free.

Mutex::lock_shared()

Blocks the calling thread, if necessary, until this `Mutex` is either free,

or in shared mode, and then acquires a share of it. Note that

`lock_shared()` will block if some other thread has an exclusive/writer

lock on the mutex.

Mutex::unlock_shared()

Releases a read share of this `Mutex`. `unlock_shared` may return a mutex

to the free state if this thread holds the last reader lock on the mutex.

Note that you cannot call `unlock_shared()` on a mutex held in write mode.

Mutex::try_lock_shared()

If the mutex can be acquired without blocking, acquires this mutex for

shared access and returns `true`. Otherwise, returns `false`. Returns

`true` with high probability if the `Mutex` was free or shared.