[thread.sema]

A counting semaphore is a semaphore object that models a non-negative resource count.

A binary semaphore is a semaphore object that has only two states.

A binary semaphore should be more efficient than the default implementation of a counting semaphore with a unit resource count.

32.8.2 Header <semaphore> synopsis [semaphore.syn]

32.8.3 Class template counting_semaphore [thread.sema.cnt]

namespace std { template<ptrdiff_t least_max_value = implementation-defined> class counting_semaphore { public: static constexpr ptrdiff_t max() noexcept; constexpr explicit counting_semaphore(ptrdiff_t desired); ~counting_semaphore(); counting_semaphore(const counting_semaphore&) = delete; counting_semaphore& operator=(const counting_semaphore&) = delete; void release(ptrdiff_t update = 1); void acquire(); bool try_acquire() noexcept; template<class Rep, class Period> bool try_acquire_for(const chrono::duration<Rep, Period>& rel_time); template<class Clock, class Duration> bool try_acquire_until(const chrono::time_point<Clock, Duration>& abs_time); private: ptrdiff_t counter; / exposition only }; }

Class template counting_semaphore maintains an internal counter that is initialized when the semaphore is created.

The counter is decremented when a thread acquires the semaphore, and is incremented when a thread releases the semaphore.

If a thread tries to acquire the semaphore when the counter is zero, the thread will block until another thread increments the counter by releasing the semaphore.

Concurrent invocations of the member functions of counting_semaphore, other than its destructor, do not introduce data races.

🔗

static constexpr ptrdiff_t max() noexcept;

Returns: The maximum value of counter.

This value is greater than or equal to least_max_value.

🔗

constexpr explicit counting_semaphore(ptrdiff_t desired);

Preconditions: desired >= 0 is true, and desired <= max() is true.

Throws: Nothing.

🔗

void release(ptrdiff_t update = 1);

Preconditions: update >= 0 is true, and update <= max() - counter is true.

Effects: Atomically execute counter += update.

Then, unblocks any threads that are waiting for counter to be greater than zero.

Synchronization: Strongly happens before invocations of try_acquire that observe the result of the effects.

Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).

🔗

bool try_acquire() noexcept;

Effects: Attempts to atomically decrement counter if it is positive, without blocking.

If counter is not decremented, there is no effect and try_acquire immediately returns.

An implementation may fail to decrement counter even if it is positive.

[Note 1:

This spurious failure is normally uncommon, but allows interesting implementations based on a simple compare and exchange ([atomics]).

— end note]

An implementation should ensure that try_acquire does not consistently return false in the absence of contending semaphore operations.

Returns: true if counter was decremented, otherwise false.

🔗

void acquire();

Effects: Repeatedly performs the following steps, in order:

(15.1)
Evaluates try_acquire().

If the result is true, returns.
(15.2)
Blocks on *this until counter is greater than zero.

Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).

🔗

template<class Rep, class Period>
  bool try_acquire_for(const chrono::duration<Rep, Period>& rel_time);
template<class Clock, class Duration>
  bool try_acquire_until(const chrono::time_point<Clock, Duration>& abs_time);

Effects: Repeatedly performs the following steps, in order:

(18.1)
Evaluates try_acquire().

If the result is true, returns true.
(18.2)
Blocks on *this until counter is greater than zero or until the timeout expires.

If it is unblocked by the timeout expiring, returns false.

The timeout expires ([thread.req.timing]) when the current time is after abs_time (for try_acquire_until) or when at least rel_time has passed from the start of the function (for try_acquire_for).

Throws: Timeout-related exceptions ([thread.req.timing]), or system_error when a non-timeout-related exception is required ([thread.req.exception]).

Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).