# Mutex

[req.mutex]

The mutexes and locks have relatively spartan interfaces that are designed for high performance. The interfaces enforce the scoped locking pattern, which is widely used in C++ libraries because:

- Does not require to remember to release the lock

- Releases the lock if an exception is thrown out of the mutual exclusion region protected by the lock

There are two parts of the pattern: a mutex object, for which construction of a lock object acquires a lock on the mutex and destruction of the lock object releases the lock. Here is an example:

    {
        // Construction of myLock acquires lock on myMutex
        M::scoped_lock myLock( myMutex );
        // ... actions to be performed while holding the lock ...
        // Destruction of myLock releases lock on myMutex
    }

If the actions throw an exception, the lock is automatically released as the block is exited.

    class M {
        // Implementation specifics
        // ...

        // Represents acquisition of a mutex
        class scoped_lock {
        public:
            constexpr scoped_lock() noexcept;
            scoped_lock(M& m);
            ~scoped_lock();

            scoped_lock(const scoped_lock&) = delete;
            scoped_lock& operator=(const scoped_lock&) = delete;

            void acquire(M& m);
            bool try_acquire(M& m);
            void release();
        };
    };

A type M satisfies the Mutex requirements if it meets the following conditions:

type M::scoped_lock

  Corresponding scoped lock type.

M::scoped_lock()

  Constructs `scoped_lock` without acquiring mutex.

M::scoped_lock(M&)

  Constructs `scoped_lock` and acquire the lock on a provided mutex.

M::~scoped_lock()

  Releases a lock (if acquired).

void M::scoped_lock::acquire(M&)

  Acquires a lock on a provided mutex.

bool M::scoped_lock::try_acquire(M&)

  Attempts to acquire a lock on a provided mutex. Returns true if the lock is acquired, false otherwise.

void M::scoped_lock::release()

  Releases an acquired lock.

Also, the `Mutex` type requires a set of traits to be defined:

static constexpr bool M::is_rw_mutex

  True if mutex is a reader-writer mutex; false, otherwise.

static constexpr bool M::is_recursive_mutex

  True if mutex is a recursive mutex; false, otherwise.

static constexpr bool M::is_fair_mutex

  True if mutex is fair; false, otherwise.

A mutex type and an `M::scoped_lock` type are neither copyable nor movable.

The following table summarizes the library classes that model the `Mutex` requirement and provided guarantees.

Provided guarantees for Mutexes that model the Mutex requirement
. | Fair | Reentrant
--- | --- | ---
`mutex` | No | No
`spin_mutex` | No | No
`speculative_spin_mutex` | No | No
`queuing_mutex` | Yes | No
`null_mutex` | Yes | Yes

Note

Implementation is allowed to have an opposite guarantees (positive) in case of negative statements from the table above.

See the oneAPI Threading Building Blocks Developer Guide for description of the mutex properties and the rationale for null mutexes.

See also:

- mutex

- spin_mutex

- speculative_spin_mutex

- queuing_mutex

- null_mutex