32 Concurrency support library [thread] (original) (raw)

32.8.1 General [thread.sema.general]

Semaphores are lightweight synchronization primitives used to constrain concurrent access to a shared resource.

They are widely used to implement other synchronization primitives and, whenever both are applicable, can be more efficient than condition variables.

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.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; };}

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.

least_max_value shall be non-negative; otherwise the program is ill-formed.

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, anddesired <= max() is true.

Effects: Initializes counter with desired.

void release(ptrdiff_t update = 1);

Preconditions: update >= 0 is true, andupdate <= 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_acquirethat observe the result of the effects.

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 andtry_acquire immediately returns.

An implementation may fail to decrement countereven 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_acquiredoes not consistently return falsein the absence of contending semaphore operations.

Returns: true if counter was decremented, otherwise false.

Effects: Repeatedly performs the following steps, in order:

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:

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).