This paper has been taken from Section 3 of P0159R0, which describes proposed extensions for concurrency. We propose the section numbered 33.7 below for inclusion in the C++ standard, after 33.6 [futures]. As P0159R0 has been available since 2015 without any recorded objections, and since it represents commonly used concurrency features, we believe it is suitable for inclusion as-is.

A previous version of this paper was published as N4392

The following changes have been made to P0159R0.

The main section has been renumbered to reflect its proposed position in the standard.

All functions and classes have been moved into the std namespace.

We propose the following additional wording beyond P0159R0 that clarifies some ambiguities in the original wording. This has been added in the paragraph below so that the committee has the option of accepting P0159R0 as written without any additions, or of including this change.

The wording for arrive_and_drop in Section 33.7.6 is ambiguous, as it implies that the first action is to remove the thread from the set of participating threads. Because the completion phase is defined to run in one of the participating threads, this wording would imply that the phase cannot run in any thread that calls arrive_and_drop.

We propose the following wording to replace paragraph 13 in Section 33.7.6.

We propose to add the following clause from the Concurrency TS to the C++20 working draft, as described below.

This section describes various concepts related to thread coordination, and defines the latch, barrier and flex_barrier classes.

In this subclause, a synchronization point represents a point at which a thread may block until a given condition has been reached.

Latches are a thread coordination mechanism that allow one or more threads to block until an operation is completed. An individual latch is a single-use object; once the operation has been completed, the latch cannot be reused.

namespace std {
  class latch {
   public:
    explicit latch(ptrdiff_t count);
    latch(const latch&) = delete;

    latch& operator=(const latch&) = delete;
    ~latch();


    void count_down_and_wait();
    void count_down(ptrdiff_t n = 1);

    bool is_ready() const noexcept;
    void wait() const;

   private:
    ptrdiff_t counter_; // exposition only
  };
} // namespace std

A latch maintains an internal counter_ that is initialized when the latch is created. Threads may block at a synchronization point waiting for counter_ to be decremented to 0. When counter_ reaches 0, all such blocked threads are released.

Calls to count_down_and_wait(), count_down(), wait(), and is_ready() behave as atomic operations.

explicit latch(ptrdiff_t count);

~latch();

void count_down_and_wait();

void count_down(ptrdiff_t n = 1);

void wait() const;

is_ready() const noexcept;

Barriers are a thread coordination mechanism that allow a set of participating threads to block until an operation is completed. Unlike a latch, a barrier is reusable: once the participating threads are released from a barrier's synchronization point, they can re-use the same barrier. It is thus useful for managing repeated tasks, or phases of a larger task, that are handled by multiple threads.

The barrier types are the standard library types barrier and flex_barrier. They shall meet the requirements set out in this subclause. In this description, b denotes an object of a barrier type.

Each barrier type defines a completion phase as a (possibly empty) set of effects. When the member functions defined in this subclause arrive at the barrier's synchronization point, they have the following effects:

1. When all threads in the barrier's set of participating threads are blocked at its synchronization point, one participating thread is unblocked and executes the barrier type's completion phase.
2. When the completion phase is completed, all other participating threads are unblocked. The end of the completion phase synchronizes with the returns from all calls unblocked by its completion.

The expression b.arrive_and_wait() shall be well-formed and have the following semantics:

void arrive_and_wait();

The expression b.arrive_and_drop() shall be well-formed and have the following semantics:

void arrive_and_drop();

Calls to arrive_and_wait() and arrive_and_drop() never introduce data races with themselves or each other.

namespace std {
  class barrier;
  class flex_barrier;
} // namespace std

barrier is a barrier type whose completion phase has no effects. Its constructor takes a parameter representing the initial size of its set of participating threads.

class barrier {
 public:
  explicit barrier(ptrdiff_t num_threads);
  barrier(const barrier&) = delete;

  barrier& operator=(const barrier&) = delete;
  ~barrier();

  void arrive_and_wait();
  void arrive_and_drop();
};

explicit barrier(ptrdiff_t num_threads);

~barrier();

flex_barrier is a barrier type whose completion phase can be controlled by a function object.

class flex_barrier {
 public:
  template <class F>
    flex_barrier(ptrdiff_t num_threads, F completion);
  explicit flex_barrier(ptrdiff_t num_threads);
  flex_barrier(const flex_barrier&) = delete;
  flex_barrier& operator=(const flex_barrier&) = delete;

  ~flex_barrier();

  void arrive_and_wait();
  void arrive_and_drop();

 private:
  function<ptrdiff_t()> completion_;  // exposition only
};

The completion phase calls completion_(). If this returns -1, then the set of participating threads is unchanged. Otherwise, the set of participating threads becomes a new set with a size equal to the returned value. [ Note: If completion_() returns 0 then the set of participating threads becomes empty, and this object may only be destroyed. — end note ]

template <class F>
flex_barrier(ptrdiff_t num_threads, F completion);
  

explicit flex_barrier(ptrdiff_t num_threads);

~flex_barrier();