.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0

===== 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:

.. code:: cpp

{ // 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.

.. code:: cpp

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:

.. namespace:: mutex_type

.. cpp:type:: M::scoped_lock

Corresponding scoped lock type.

.. namespace:: mutex_func

.. cpp:function:: M::scoped_lock()

Constructs ``scoped_lock`` without acquiring mutex.

.. cpp:function:: M::scoped_lock(M&)

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

.. cpp:function:: M::~scoped_lock()

Releases a lock (if acquired).

.. cpp:function:: void M::scoped_lock::acquire(M&)

Acquires a lock on a provided mutex.

.. cpp:function:: 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.

.. cpp:function:: void M::scoped_lock::release()

Releases an acquired lock.

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

.. cpp:member:: static constexpr bool M::is_rw_mutex

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

.. cpp:member:: static constexpr bool M::is_recursive_mutex

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

.. cpp:member:: 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.

.. table:: 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.