std::barrier

Defined in header `<barrier>`
template<class CompletionFunction = /* see below */> class barrier;		(since C++20)

The class template std::barrier provides a thread-coordination mechanism that allows at most an expected number of threads to block until the expected number of threads arrive at the barrier. Unlike std::latch, barriers are reusable: once the arriving threads are unblocked from a barrier phase's synchronization point, the same barrier can be reused.

A barrier object's lifetime consists of a sequence of barrier phases. 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 be unblocked when the phase completion step is run.

A barrier phase consists following steps:

The expected count is decremented by each call to arrive or arrive_and_drop.
When the expected count reaches zero, the phase completion step is run. The completion step invokes the completion function object, and unblocks all threads 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 the specialization std::barrier<> (using the default template argument), 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. And the behavior is undefined if any of the barrier object's member functions other than wait are called during the completion step.
When the completion step finishes, the expected count is reset to the value specified at construction less the number of calls to arrive_and_drop since, and the next barrier phase begins.

Concurrent invocations of the member functions of barrier, except for the destructor, do not introduce data races.

(constructor)	constructs a `barrier` (public member function) [edit]
(destructor)	destroys the `barrier` (public member function) [edit]
operator= [deleted]	`barrier` is not assignable (public member function)
arrive	arrives at barrier and decrements the expected count (public member function) [edit]
wait	blocks at the phase synchronization point until its phase completion step is run (public member function) [edit]
arrive_and_wait	arrives at barrier and decrements the expected count by one, then blocks until current phase completes (public member function) [edit]
arrive_and_drop	decrements both the initial expected count for subsequent phases and the expected count for current phase by one (public member function) [edit]
Constants
max [static]	the maximum value of expected count supported by the implementation (public static member function) [edit]

Example

Run this code

#include <barrier>
#include <iostream>
#include <mutex>
#include <string>
#include <thread>
 
int main() {
  auto report = [](std::string const& s) {
    static std::mutex sync;
    std::scoped_lock lock{sync};
    std::cout << "  " << s << '\n';
  };
 
  struct job {
    const std::string name;
    std::string product{"not worked"};
    std::thread thread{};
  } jobs[] = { {"anil"}, {"busara"}, {"carl"} };
 
  char const* phases[] = {
    "Starting...", "Cleaning up...", "All finished." };
  std::barrier sync_point(std::size(jobs), [&phases]{ 
    // mutex not needed here...
    static int phase = 0;
    std::cout << "... done\n" << phases[++phase] << '\n';
  });
 
  auto work = [&](int job_ix) {
    auto& my_job = jobs[job_ix];
    my_job.product = my_job.name + " worked";
    report(my_job.product);
    sync_point.arrive_and_wait();
 
    my_job.product = my_job.name + " cleaned";
    report(my_job.product);
    sync_point.arrive_and_wait();
  };
 
  std::cout << *phases << '\n';
  for (auto& job : jobs) {
    job.thread = std::thread{work, &job - jobs};
  }
  for (auto& job : jobs) {
    job.thread.join();
  }
}

Possible output:

Starting...
  anil worked
  busara worked
  carl worked
... done
Cleaning up...
  busara cleaned
  carl cleaned
  anil cleaned
... done
All finished.

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
barrier::barrier
barrier::~barrier
barrier::arrive
barrier::wait
barrier::arrive_and_wait
barrier::arrive_and_drop
Constants
barrier::max

Name	Definition
`arrival_token`	an unspecified object type meeting requirements of MoveConstructible, MoveAssignable and Destructible

cppreference.com

Namespaces

Variants

Views

Actions

std::barrier

Contents

Template parameters

Member types

Member functions

Constants

Example

See also

Navigation

Toolbox

CompletionFunction	-	a function object type
- `CompletionFunction` must meet the requirements of MoveConstructible and Destructible. std::is_nothrow_invocable_v<CompletionFunction&> must be true.