tmc::semaphore

An async version of std::counting_semaphore.

API Reference

class semaphore : protected tmc::detail::waiter_data_base

An async version of std::counting_semaphore.

Public Types

using half_word = tmc::detail::half_word

The count is packed into half a machine word along with the awaiter count. Thus it is only allowed half a machine word of bits.

Public Functions

inline semaphore(half_word InitialCount) noexcept

Sets the initial number of resources available in the semaphore. This is only an initial value and not a maximum; by calling release(), the number of resources available may exceed this initial value.

inline size_t count() noexcept

Returns an estimate of the current number of available resources. This value is not guaranteed to be consistent with any other operation. Even if this returns non-zero, awaiting afterward may suspend. Even if this returns zero, awaiting afterward may not suspend.

void release(size_t ReleaseCount = 1) noexcept

Increases the available resources by ReleaseCount. If there are awaiters, they will be awoken until all resources have been consumed. Does not symmetric transfer; awaiters will be posted to their executors.

inline aw_semaphore_co_release co_release() noexcept

Increases the available resources by 1. If there are awaiters, 1 will be awoken and the resource will be transferred to it. The awaiter may be resumed by symmetric transfer if it is eligible (it resumes on the same executor and priority as the caller).

inline aw_acquire operator co_await() noexcept

Tries to acquire the semaphore. If no resources are ready, will suspend until a resource becomes ready.

inline aw_semaphore_acquire_scope acquire_scope() noexcept

Tries to acquire the semaphore. If no resources are ready, will suspend until a resource becomes ready, then transfer the ownership to this task. Returns an object that will release the resource (and resume an awaiter) when it goes out of scope.

~semaphore()

On destruction, any awaiters will be resumed.

class aw_semaphore_acquire_scope : private tmc::detail::AwaitTagNoGroupAsIs

Same as aw_semaphore but returns a nodiscard semaphore_scope that releases the semaphore on destruction.

class semaphore_scope

The semaphore will be released when this goes out of scope.

Public Functions

~semaphore_scope()

Releases the semaphore on destruction. Does not symmetric transfer.