32 Thread support library [thread]

32.8 Coordination types [thread.coord]

32.8.2 Barriers [thread.barrier]

1
#
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.
[ Note
:
A barrier is useful for managing repeated tasks that are handled by multiple threads.
— end note
 ]

32.8.2.1 Header <barrier> synopsis [barrier.syn]

namespace std {
  template<class CompletionFunction = see below>
    class barrier;
}

32.8.2.2 Class template barrier [thread.barrier.class]

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;

    [[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
    void wait(arrival_token&& arrival) const;

    void arrive_and_wait();
    void arrive_and_drop();

  private:
    CompletionFunction completion;      // exposition only
  };
}
1
#
Each barrier phase consists of the following steps:
  • (1.1)
    The expected count is decremented by each call to arrive or arrive_­and_­drop.
  • (1.2)
    When the expected count reaches zero, the phase completion step is run. For the specialization with the default value of the CompletionFunction template parameter, the completion step is run as part of the call to arrive or arrive_­and_­drop that caused the expected count to reach zero. For other specializations, the completion step is run on one of the threads that arrived at the barrier during the phase.
  • (1.3)
    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.
2
#
Each phase defines a phase synchronization point.
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.
3
#
The phase completion step that is executed at the end of each phase has the following effects:
  • (3.1)
    Invokes the completion function, equivalent to completion().
  • (3.2)
    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.
4
#
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.
5
#
CompletionFunction shall meet the Cpp17MoveConstructible (Table 28) and Cpp17Destructible (Table 32) requirements.
is_­nothrow_­invocable_­v<CompletionFunction&> shall be true.
6
#
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 27) and completion() has no effects.
7
#
barrier​::​arrival_­token is an unspecified type, such that it meets the Cpp17MoveConstructible (Table 28), Cpp17MoveAssignable (Table 30), and Cpp17Destructible (Table 32) requirements.
🔗
static constexpr ptrdiff_t max() noexcept;
8
#
Returns: The maximum expected count that the implementation supports.
🔗
constexpr explicit barrier(ptrdiff_t expected, CompletionFunction f = CompletionFunction());
9
#
Preconditions: expected >= 0 is true and expected <= max() is true.
10
#
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).
Starts the first phase.
[ Note
:
If expected is 0 this object can only be destroyed.
— end note
 ]
11
#
Throws: Any exception thrown by CompletionFunction's move constructor.
🔗
[[nodiscard]] arrival_token arrive(ptrdiff_t update = 1);
12
#
Preconditions: update > 0 is true, and update is less than or equal to the expected count for the current barrier phase.
13
#
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.
14
#
Synchronization: The call to arrive strongly happens before the start of the phase completion step for the current phase.
15
#
Returns: The constructed arrival_­token object.
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]).
18
#
[ Note
:
This call can cause the completion step for the current phase to start.
— end note
 ]
🔗
void wait(arrival_token&& arrival) const;
19
#
Preconditions: arrival is associated with the phase synchronization point for the current phase or the immediately preceding phase of the same barrier object.
20
#
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
:
If arrival is associated with the synchronization point for a previous phase, the call returns immediately.
— end note
 ]
21
#
Throws: system_­error when an exception is required ([thread.req.exception]).
22
#
Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).
🔗
void arrive_and_wait();
23
#
Effects: Equivalent to: wait(arrive()).
🔗
void arrive_and_drop();
24
#
Preconditions: The expected count for the current barrier phase is greater than zero.
25
#
Effects: Decrements the initial expected count for all subsequent phases by one.
Then decrements the expected count for the current phase by one.
26
#
Synchronization: The call to arrive_­and_­drop strongly happens before the start of the phase completion step for the current phase.
27
#
Throws: system_­error when an exception is required ([thread.req.exception]).
28
#
Error conditions: Any of the error conditions allowed for mutex types ([thread.mutex.requirements.mutex]).
29
#
[ Note
:
This call can cause the completion step for the current phase to start.
— end note
 ]