tmc::mutex

This file documents tmc::mutex; however, tmc::ex_braid, which is a serializing executor, can be used in similar ways.

An async version of std::mutex.

API Reference

class mutex : protected tmc::detail::waiter_data_base

An async version of std::mutex.

Public Functions

inline mutex() noexcept

Mutex begins in the unlocked state.

inline bool is_locked() noexcept

Returns true if some task is holding the mutex. This value is not guaranteed to be consistent with any other operation. Even if this returns false, awaiting afterward may suspend.

void unlock() noexcept

Unlocks the mutex. If there are any awaiters, an awaiter will be resumed and the lock will be re-locked and transferred to that awaiter. Does not symmetric transfer; the awaiter will be posted to its executor.

inline aw_mutex_co_unlock co_unlock() noexcept

Unlocks the mutex. If there are any awaiters, an awaiter will be resumed and the lock will be re-locked and transferred to that awaiter. The awaiter may be resumed by symmetric transfer if it is eligible (it resumes on the same executor and priority as the caller).

template<typename Result>
inline aw_mutex_co_unlock_return<Result> co_unlock_return(Result &&result) noexcept

Unlocks the mutex. If there are any awaiters, an awaiter will be resumed and the lock will be re-locked and transferred to that awaiter. Also completes this coroutine immediately, returns the result back to its parent coroutine, and resumes the parent coroutine. Both the resuming awaiter and the parent coroutine will be checked for symmetric transfer eligibility; otherwise they will be posted back to their respective executors.

This effectively contains a co_return statement, ending the current coroutine; nothing will be executed after it in the current scope.

The purpose of this is to skip a round-trip through the executor when you want to unlock this mutex immediately before returning.

// You can replace this:
co_await mut.co_unlock();
co_return result;

// With this:
co_await mut.co_unlock_return(result);
std::unreachable();

inline aw_mutex_co_unlock_return<void> co_unlock_return() noexcept

Unlocks the mutex. If there are any awaiters, an awaiter will be resumed and the lock will be re-locked and transferred to that awaiter. Also completes this coroutine immediately and resumes the parent coroutine. Both the resuming awaiter and the parent coroutine will be checked for symmetric transfer eligibility; otherwise they will be posted back to their respective executors.

This effectively contains a co_return statement, ending the current coroutine; nothing will be executed after it in the current scope.

The purpose of this is to skip a round-trip through the executor when you want to unlock this mutex immediately before returning.

// You can replace this:
co_await mut.co_unlock();
co_return;

// With this:
co_await mut.co_unlock_return();
std::unreachable();

inline aw_acquire operator co_await() noexcept

Tries to acquire the mutex. If it is locked by another task, will suspend until it can be locked by this task, then transfer the ownership to this task. Not re-entrant.

inline aw_mutex_lock_scope lock_scope() noexcept

Tries to acquire the mutex. If it is locked by another task, will suspend until it can be locked by this task, then transfer the ownership to this task. Not re-entrant. Returns an object that will unlock the mutex (and resume an awaiter) when it goes out of scope.

~mutex()

On destruction, any awaiters will be resumed.

class aw_mutex_lock_scope : private tmc::detail::AwaitTagNoGroupAsIs

Same as aw_acquire but returns a nodiscard mutex_scope that unlocks the mutex on destruction.

class mutex_scope

The mutex will be unlocked when this goes out of scope.

Public Functions

~mutex_scope()

Unlocks the mutex on destruction. Does not symmetric transfer.