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.

oneAPI Specification 1.1-rev-1 documentation

Mutex¶