carb::cpp::latch

Defined in carb/cpp/Latch.h

class latch

Implements a C++20 latch in C++14 semantics.

The latch class is a downward counter of type std::ptrdiff_t which can be used to synchronize threads. The value of the counter is initialized on creation. Threads may block on the latch until the counter is decremented to zero. There is no possibility to increase or reset the counter, which makes the latch a single-use barrier.

Unlike barrier, latch can be decremented by a participating thread more than once.

Thread Safety

Concurrent invocations of the member functions of latch, except for the destructor, do not introduce data races.

Public Functions

inline explicit constexpr latch(ptrdiff_t expected) noexcept

Constructor.

Constructs a latch and initializes its internal counter. The behavior is undefined if expected is negative or greater than max().

Parameters

expected – The initial value of the internal counter.

inline ~latch() noexcept

Destructor.

The behavior is undefined if any thread is concurrently calling a member function of the latch.

Note

This implementation waits until all waiting threads have woken, but this is a stronger guarantee than the standard.

inline void count_down(ptrdiff_t update = 1) noexcept

Decrements the counter in a non-blocking manner.

Atomically decrements the internal counter by update without blocking the caller. If the count reaches zero, all blocked threads are unblocked.

If update is greater than the value of the internal counter or is negative, the behavior is undefined.

This operation strongly happens-before all calls that are unblocked on this latch.

Parameters

update – The value by which the internal counter is decreased.

Throws

std::system_error – According to the standard, but this implementation does not throw. Instead an assertion occurs.

inline bool try_wait() const noexcept

Tests if the internal counter equals zero.

Returns true only if the internal counter has reached zero. This function may spuriously return false with very low probability even if the internal counter has reached zero.

Note

The reason why a spurious result is permitted is to allow implementations to use a memory order more relaxed than std::memory_order_seq_cst.

Returns

With very low probability false, otherwise cnt == 0 where cnt is the value of the internal counter.

inline void wait() const noexcept

Blocks until the counter reaches zero.

Blocks the calling thread until the internal counter reaches zero. If it is zero already, returns immediately.

Throws

std::system_error – According to the standard, but this implementation does not throw.

inline void arrive_and_wait(ptrdiff_t update = 1) noexcept

Decrements the counter and blocks until it reaches zero.

Atomically decrements the internal counter by update and (if necessary) blocks the calling thread until the counter reaches zero. Equivalent to count_down(update); wait();.

If update is greater than the value of the internal counter or is negative, the behavior is undefined.

Parameters

update – The value by which the internal counter is decreased.

Throws

std::system_error – According to the standard, but this implementation does not throw. Instead an assertion occurs.

Public Static Functions

static inline constexpr ptrdiff_t max() noexcept

The maximum value of counter supported by the implementation.

Returns

The maximum value of counter supported by the implementation.