carb::cpp::barrier

Defined in carb/cpp/Barrier.h

Classes

• carb::cpp::barrier::arrival_token: An object type meeting requirements of MoveConstructible, MoveAssignable and Destructible.

template<class CompletionFunction = detail::NullFunction>
class barrier

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

A barrier is a thread coordination mechanism whose lifetime consists of a sequence of barrier phases, where each phase allows at most an expected number of threads to block until the expected number of threads arrive at the barrier. A barrier is useful for managing repeated tasks that are handled by multiple threads.

See also

https://en.cppreference.com/w/cpp/thread/barrier

Template Parameters

CompletionFunction – A function object type that must meet the requirements of MoveConstructible and Destructible. std::is_nothrow_invocable_v<CompletionFunction&> must be true. The default template argument is an unspecified function object type that additionally meets the requirements of DefaultConstructible. Calling an lvalue of it with no arguments has no effects. Every barrier behaves as if it holds an exposition-only non-static data member completion_ of type CompletionFunction and calls it by completion_() on every phase completion step.

Public Functions

inline explicit constexpr barrier(ptrdiff_t expected, CompletionFunction f = CompletionFunction{})

Constructor.

Sets both the initial expected count for each phase and the current expected count for the first phase to expected, initializes the completion function object with std::move(f), and then starts the first phase. The behavior is undefined if expected is negative or greater than max().

Parameters

• expected – Initial value of the expected count.

• f – Completion function object to be called on phase completion step.

Throws

std::exception – Any exception thrown by CompletionFunction’s move constructor.

inline ~barrier()

Destructor.

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

Note

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

inline arrival_token arrive(ptrdiff_t update = 1)

Arrives at barrier and decrements the expected count.

Constructs an arrival_token object associated with the phase synchronization point for the current phase. Then, decrements the expected count by update.

This function executes atomically. The call to this function strongly happens-before the start of the phase completion step for the current phase.

The behavior is undefined if update is less than or equal zero or greater than the expected count for the current barrier phase.

See also

wait()

Parameters

update – The value by which the expected count is decreased.

Throws

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

Returns

The constructed arrival_token object.

inline void wait(arrival_token &&arrival) const

Blocks at the phase synchronization point until its phase completion step is run.

If arrival is associated with the phase synchronization point for the current phase of *this, blocks at the synchronization point associated with arrival until the phase completion step of the synchronization point’s phase is run.

Otherwise if arrival is associated with the phase synchronization point for the immediately preceding phase of *this, returns immediately.

Otherwise, i.e. if arrival is associated with the phase synchronization point for an earlier phase of *this or any phase of a barrier object other than *this, the behavior is undefined.

Parameters

arrival – An arrival_token obtained by a previous call to arrive() on the same barrier.

Throws

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

inline void arrive_and_wait()

Arrives at barrier and decrements the expected count by one, then blocks until the current phase completes.

Atomically decrements the expected count by one, then blocks at the synchronization point for the current phase until the phase completion step of the current phase is run. Equivalent to wait(arrive()).

The behavior is undefined if the expected count for the current phase is zero.

Note

If the current expected count is decremented to zero in the call to this function, the phase completion step is run and this function does not block. If the current expected count is zero before calling this function, the initial expected count for all subsequent phases is also zero, which means the barrier cannot be reused.

Throws

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

inline void arrive_and_drop()

Decrements both the initial expected count for subsequent phases and the expected count for current phase by one.

This function is executed atomically. The call to this function strongly happens-before the start of the phase completion step for the current phase.

The behavior is undefined if the expected count for the current phase is zero.

Note

This function can cause the completion step for the current phase to start. If the current expected count is zero before calling this function, the initial expected count for all subsequent phases is also zero, which means the barrier cannot be reused.

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

Returns the maximum value of expected count supported by the implementation.

Returns

the maximum value of expected count supported by the implementation.

class arrival_token

An object type meeting requirements of MoveConstructible, MoveAssignable and Destructible.

See also

arrive() wait()

Public Functions

arrival_token() = default

Constructor.

inline arrival_token(arrival_token &&rhs)

Move constructor.

Parameters

rhs – Other arrival_token to move from. rhs is left in a valid but empty state.

inline arrival_token &operator=(arrival_token &&rhs)

Move-assign operator.

Parameters

rhs – Other arrival_token to move from. rhs is left in a valid but empty state.

Returns

*this