32 Concurrency support library [thread]
namespace std {
template<class CompletionFunction = see below>
class barrier {
public:
using arrival_token = see below;
static constexpr ptrdiff_t max() noexcept;
constexpr explicit barrier(ptrdiff_t expected,
CompletionFunction f = CompletionFunction());
~barrier();
barrier(const barrier&) = delete;
barrier& operator=(const barrier&) = delete;
arrival_token arrive(ptrdiff_t update = 1);
void wait(arrival_token&& arrival) const;
void arrive_and_wait();
void arrive_and_drop();
private:
CompletionFunction completion;
};
}
Each
barrier phase consists of the following steps:
The expected count is decremented
by each call to
arrive or
arrive_and_drop.Exactly once after the expected count reaches zero, a thread
executes the completion step during its call
to
arrive,
arrive_and_drop, or
wait,
except that it is
implementation-defined
whether the step executes if no thread calls
wait.When the completion step finishes,
the expected count is reset
to what was specified by the
expected argument to the constructor,
possibly adjusted by calls to
arrive_and_drop, and
the next phase starts
.
Threads that arrive at the barrier during the phase
can block on the phase synchronization point by calling
wait, and
will remain blocked until the phase completion step is run
. The
phase completion step
that is executed at the end of each phase has the following effects:
Invokes the completion function, equivalent to
completion().Unblocks all threads that are blocked on the phase synchronization point
.
The end of the completion step strongly happens before
the returns from all calls that were unblocked by the completion step
.For specializations that do not have
the default value of the
CompletionFunction template parameter,
the behavior is undefined if any of the barrier object's member functions
other than
wait are called while the completion step is in progress
.Concurrent invocations of the member functions of
barrier,
other than its destructor, do not introduce data races
.The member functions
arrive and
arrive_and_drop
execute atomically
. is_nothrow_invocable_v<CompletionFunction&> shall be
true. The default value of the
CompletionFunction template parameter is
an unspecified type, such that,
in addition to satisfying the requirements of
CompletionFunction,
it meets the
Cpp17DefaultConstructible
requirements (Table
30) and
completion() has no effects
.static constexpr ptrdiff_t max() noexcept;
Returns: The maximum expected count that the implementation supports
. constexpr explicit barrier(ptrdiff_t expected,
CompletionFunction f = CompletionFunction());
Preconditions:
expected >= 0 is
true and
expected <= max() is
true. Effects: Sets both the initial expected count for each barrier phase and
the current expected count for the first phase to
expected. Initializes
completion with
std::move(f).[
Note 1:
If
expected is 0 this object can only be destroyed
. —
end note]
Throws: Any exception thrown by
CompletionFunction's move constructor
. arrival_token arrive(ptrdiff_t update = 1);
Preconditions:
update > 0 is
true, and
update is less than or equal to
the expected count for the current barrier phase
. Effects: Constructs an object of type
arrival_token
that is associated with the phase synchronization point for the current phase
. Then, decrements the expected count by
update.Synchronization: The call to
arrive strongly happens before
the start of the phase completion step for the current phase
. Returns: The constructed
arrival_token object
. [
Note 2:
This call can cause the completion step for the current phase to start
. —
end note]
void wait(arrival_token&& arrival) const;
Preconditions:
arrival is associated with
the phase synchronization point for the current phase or
the immediately preceding phase of the same barrier object
. Effects: Blocks at the synchronization point associated with
std::move(arrival)
until the phase completion step of the synchronization point's phase is run
. [
Note 3:
If
arrival is associated with the synchronization point
for a previous phase, the call returns immediately
. —
end note]
Effects: Equivalent to:
wait(arrive()). Preconditions: The expected count for the current barrier phase is greater than zero
. Effects: Decrements the initial expected count for all subsequent phases by one
. Then decrements the expected count for the current phase by one
.Synchronization: The call to
arrive_and_drop strongly happens before
the start of the phase completion step for the current phase
. [
Note 4:
This call can cause the completion step for the current phase to start
. —
end note]