ion::Barrier< CompletionFunction > Class Template Reference

Reusable thread-coordination mechanism modelled after std::barrier. More...

#include <ion/barrier.hpp>

Public Member Functions
constexpr	Barrier (std::ptrdiff_t expected, CompletionFunction func=CompletionFunction()) noexcept
	Construct new barrier with an expected count of expected.
auto	Arrive (std::ptrdiff_t n=1) noexcept -> ArrivalToken
	Arrives at barrier, possibly executing completion function and returns token.
void	Wait (ArrivalToken &&token) const noexcept
	Block at the barrier synchronization point associated with token.
void	ArriveAndWait (std::ptrdiff_t n=1) noexcept
	Equivalent to barrier.Wait(barrier.Arrive(n))
void	ArriveAndDrop () noexcept
	Decrements both the initial expected count for subsequent phases and the expected count for current phase by one.
Barrier requires stable address and is neither copyable or movable.
	Barrier (Barrier const &)=delete
Barrier &	operator= (Barrier const &)=delete

Static Public Member Functions
static constexpr auto	Max () noexcept -> std::ptrdiff_t

Detailed Description

template<class CompletionFunction = *unspecified*>
class ion::Barrier< CompletionFunction >

Reusable thread-coordination mechanism modelled after std::barrier.

Modelled after C++20 std::barrier but does not perform system calls or yields and as such is more suitable in a real-time environment. Notable differences:

• Methods are noexcept as no mutexes are involved.

A Barrier phase consist of two states:

1. arrival, when threads fetch and decrement the expected count
2. departure, when all threads have arrived and will depart. The barrier is automatically reset to the next arrival phase.

Template Parameters

CompletionFunction

no-except invocable function, invoked by one of the threads that arrive at the barrier via Arrive(), ArriveAndWait() or ArriveAndDrop().

Memory Order

All calls to ArriveAndWait() or ArriveAndDrop() synchronizes-with any calls to ArriveAndWait() or Wait().

The CompletionFunction synchronizes-with calls to ArriveAndWait() or Wait() after it is executed. This means that no additional synchronization is necessary in the CompletionFunction* w.r.t. to the threads that have arrived and is waiting for departure.

Thread Safety

thread-safe

Constructor & Destructor Documentation

Barrier()

template<class CompletionFunction>

ion::Barrier< CompletionFunction >::Barrier ( std::ptrdiff_t expected, CompletionFunction func = CompletionFunction() )

explicitconstexprnoexcept

Construct new barrier with an expected count of expected.

Precondition

expected <= Barrier::Max()

Parameters

expected	Expected number of arrivals.
func	Completion function invoked once for every barrier phase. phases arrival and departure.

Member Function Documentation

Arrive()

template<class CompletionFunction>

auto ion::Barrier< CompletionFunction >::Arrive ( std::ptrdiff_t n = 1 ) -> ArrivalToken

nodiscardnoexcept

Arrives at barrier, possibly executing completion function and returns token.

Precondition

n must be > 0 and <= the expected count for the current barrier phase.

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

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 n is less than or equal to 0 or greater than the expected count for the current barrier phase.

Parameters

n	the value by which the expected count will be decreased.

Returns

ArrivalToken associated with current phase.

See also

Wait()

ArriveAndWait()

ArriveAndDrop()

template<class CompletionFunction>

void ion::Barrier< CompletionFunction >::ArriveAndDrop ( )

noexcept

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

Precondition

Expected count for current barrier phase must be >= 1.

Unlike ArriveAndWait it will not wait.

ArriveAndWait()

template<class CompletionFunction>

void ion::Barrier< CompletionFunction >::ArriveAndWait ( std::ptrdiff_t n = 1 )

noexcept

Equivalent to barrier.Wait(barrier.Arrive(n))

Parameters

n	the value by which the expected count will be decreased.

Max()

template<class CompletionFunction>

auto ion::Barrier< CompletionFunction >::Max ( ) -> std::ptrdiff_t

staticconstexprnoexcept

Returns

Maximum possible value for expected count.

Wait()

template<class CompletionFunction>

void ion::Barrier< CompletionFunction >::Wait ( ArrivalToken && token ) const

noexcept

Block at the barrier synchronization point associated with token.

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

token

Arrival token from previous call to Arrive().

See also

Arrive()