32 Thread support library [thread]

32.7 Semaphore [thread.sema]

32.7.2 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
  };
}
1
#
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.
2
#
least_­max_­value shall be non-negative; otherwise the program is ill-formed.
3
#
Concurrent invocations of the member functions of counting_­semaphore, other than its destructor, do not introduce data races.
🔗
static constexpr ptrdiff_t max() noexcept;
4
#
Returns: The maximum value of counter.
This value is greater than or equal to least_­max_­value.
🔗
constexpr explicit counting_semaphore(ptrdiff_t desired);
5
#
Preconditions: desired >= 0 is true, and desired <= max() is true.
6
#
Effects: Initializes counter with desired.
7
#
Throws: Nothing.
🔗
void release(ptrdiff_t update = 1);
8
#
Preconditions: update >= 0 is true, and update <= max() - counter is true.
9
#
Effects: Atomically execute counter += update.
Then, unblocks any threads that are waiting for counter to be greater than zero.
10
#
Synchronization: Strongly happens before invocations of try_­acquire that observe the result of the effects.
11
#
Throws: system_­error when an exception is required ([thread.req.exception]).
12
#
Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).
🔗
bool try_acquire() noexcept;
13
#
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
:
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.
14
#
Returns: true if counter was decremented, otherwise false.
🔗
void acquire();
15
#
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.
16
#
Throws: system_­error when an exception is required ([thread.req.exception]).
17
#
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);
18
#
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).
19
#
Throws: Timeout-related exceptions ([thread.req.timing]), or system_­error when a non-timeout-related exception is required ([thread.req.exception]).
20
#
Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).