FreeBSD Manual Pages
std::barrier(3) C++ Standard Libary std::barrier(3) NAME std::barrier - std::barrier Synopsis Defined in header <barrier> template< class CompletionFunction = /* see below */ > (since C++20) class barrier; The class template std::barrier provides a thread-coordination mech- anism that blocks a group of threads of known size until all threads in that group have reached the barrier. Unlike std::latch, barriers are reusable: once a group of arriving threads are unblocked, the barrier can be reused. Unlike std::latch, barri- ers execute a possibly empty callable before unblocking threads. A barrier object's lifetime consists of one or more phases. Each phase defines a phase synchronization point where waiting threads block. Threads can arrive at the barrier, but defer waiting on the phase synchronization point by calling arrive. Such threads can later block on the phase synchronization point by calling wait. A barrier phase consists of the following steps: 1. The expected count is decremented by each call to arrive or ar- rive_and_drop. 2. When the expected count reaches zero, the phase completion step is run, meaning that the completion is invoked, and all threads blocked on the phase synchronization point are unblocked. The end of the completion step strongly happens-before all calls that were unblocked by the completion step return. Exactly once after the expected count reaches zero, a thread ex- ecutes 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. 3. When the completion step finishes, the expected count is reset to the value specified at construction less the number of calls to ar- rive_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. Template parameters CompletionFunction - a function object type - CompletionFunction must meet the requirements of MoveConstructible and Destructible. std::is_nothrow_invocable_v<CompletionFunction&> must be true. The default template argument of CompletionFunction is an unspeci- fied function object type that additionally meets the requirements of DefaultCon- structible. Calling an lvalue of it with no arguments has no effects. Member objects Name Definition A completion function object of type Comple- tionFunction which completion (private) is called on every phase completion step. (exposition-only member object*) Member types Name Definition arrival_token an unspecified object type meeting requirements of MoveConstructible, MoveAssignable and Destructible Member functions constructor constructs a barrier (public member function) destructor destroys the barrier (public member function) operator= barrier is not assignable [deleted] (public member function) arrive arrives at barrier and decrements the expected count (public member function) blocks at the phase synchronization point until its phase completion wait step is run (public member function) arrives at barrier and decrements the expected count by one, then arrive_and_wait blocks until current phase completes (public member function) decrements both the initial expected count for sub- sequent phases and arrive_and_drop the expected count for current phase by one (public member function) Constants max the maximum value of expected count supported by the implementation [static] (public static member function) Notes Feature-test macro Value Std Feature 201907L (C++20) std::barrier __cpp_lib_barrier 202302L (C++20) Relaxed guarantees for phase com- pletion (DR) Example // Run this code #include <barrier> #include <iostream> #include <string> #include <syncstream> #include <thread> #include <vector> int main() { const auto workers = {"Anil", "Busara", "Carl"}; auto on_completion = []() noexcept { // locking not needed here static auto phase = "... done\n" "Cleaning up...\n"; std::cout << phase; phase = "... done\n"; }; std::barrier sync_point(std::ssize(workers), on_completion); auto work = [&](std::string name) { std::string product = " " + name + " worked\n"; std::osyncstream(std::cout) << product; // ok, op<< call is atomic sync_point.arrive_and_wait(); product = " " + name + " cleaned\n"; std::osyncstream(std::cout) << product; sync_point.arrive_and_wait(); }; std::cout << "Starting...\n"; std::vector<std::jthread> threads; threads.reserve(std::size(workers)); for (auto const& worker : workers) threads.emplace_back(work, worker); } Possible output: Starting... Anil worked Carl worked Busara worked ... done Cleaning up... Busara cleaned Carl cleaned Anil cleaned ... done Defect reports The following behavior-changing defect reports were applied retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior P2588R3 C++20 old phase completion guarantees might prevent relaxed hardware acceleration See also latch single-use thread barrier (C++20) (class) http://cppreference.com 2024.06.10 std::barrier(3)
NAME | Synopsis | Template parameters | Member objects | Member types | Member functions | Constants | Notes | Example | Possible output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::barrier&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>