std::barrier

 

C++

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

 

Concurrency support library

Threads thread (C++11) jthread (C++20) hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17) this_thread namespace get_id (C++11) yield (C++11) sleep_for (C++11) sleep_until (C++11) Cooperative cancellation stop_token (C++20) inplace_stop_token (C++26) never_stop_token (C++26) stop_source (C++20) inplace_stop_source (C++26)   stop_callback (C++20) inplace_stop_callback (C++26) stop_callback_for_t (C++26) stoppable_token (C++26) unstoppable_token (C++26) stoppable-source (C++26) stoppable-callback-for (C++26)   Mutual exclusion mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17) timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14) Generic lock management lock (C++11) lock_guard (C++11) scoped_lock (C++17) unique_lock (C++11) shared_lock (C++14) once_flag (C++11) call_once (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lockdefer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)(C++11)(C++11)(C++11) Condition variables condition_variable (C++11) condition_variable_any (C++11) notify_all_at_thread_exit (C++11) cv_status (C++11) Semaphores counting_semaphorebinary_semaphore (C++20)(C++20) Latches and Barriers latch (C++20) barrier (C++20) Futures promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11) launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11) Safe Reclamation rcu_obj_base (C++26) rcu_domain (C++26) rcu_default_domain (C++26) rcu_synchronize (C++26) rcu_barrier (C++26) rcu_retire (C++26) Hazard Pointers hazard_pointer_obj_base (C++26) hazard_pointer (C++26) make_hazard_pointer (C++26)

Atomic types atomic (C++11) atomic_ref (C++20) atomic_flag (C++11) Initialization of atomic types atomic_init (C++11)(deprecated in C++20) ATOMIC_VAR_INIT (C++11)(deprecated in C++20) ATOMIC_FLAG_INIT (C++11) Memory ordering memory_order (C++11) kill_dependency (C++11) atomic_thread_fence (C++11) atomic_signal_fence (C++11) Free functions for atomic operations atomic_storeatomic_store_explicit (C++11)(C++11) atomic_loadatomic_load_explicit (C++11)(C++11) atomic_exchangeatomic_exchange_explicit (C++11)(C++11) atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11) atomic_fetch_addatomic_fetch_add_explicit (C++11)(C++11) atomic_fetch_subatomic_fetch_sub_explicit (C++11)(C++11) atomic_fetch_andatomic_fetch_and_explicit (C++11)(C++11) atomic_fetch_oratomic_fetch_or_explicit (C++11)(C++11) atomic_fetch_xoratomic_fetch_xor_explicit (C++11)(C++11) atomic_fetch_maxatomic_fetch_max_explicit (C++26)(C++26) atomic_fetch_minatomic_fetch_min_explicit (C++26)(C++26) atomic_is_lock_free (C++11) atomic_waitatomic_wait_explicit (C++20)(C++20) atomic_notify_one (C++20) atomic_notify_all (C++20) Free functions for atomic flags atomic_flag_test_and_setatomic_flag_test_and_set_explicit (C++11)(C++11) atomic_flag_clearatomic_flag_clear_explicit (C++11)(C++11) atomic_flag_testatomic_flag_test_explicit (C++20)(C++20) atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20) atomic_flag_notify_one (C++20) atomic_flag_notify_all (C++20)

 

std::barrier

Member functions

barrier::barrier

barrier::~barrier

barrier::arrive

barrier::wait

barrier::arrive_and_wait

barrier::arrive_and_drop

Constants

barrier::max

 

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:

1. The expected count is decremented by each call to arrive or arrive_and_drop.
2. 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.
3. When the completion step finishes, the expected count is reset to the value specified in construction, possibly adjusted by calls to arrive_and_drop, and the next phase starts.

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 unspecified function object type that addtionally meets the requirements of DefaultConstructible. Calling an lvalue of it with no arguments has no effects.

Every barrier object behaves as if it holds an exposition-only non-static data member completion_ of type CompletionFunction and calls it by completion_() on every phase completion step.

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= [deleted]	barrier is not assignable (public member function)
arrive	arrives at barrier and decrements the expected count (public member function)
wait	blocks at the phase synchronization point until its phase completion step is run (public member function)
arrive_and_wait	arrives at barrier and decrements the expected count by one, then blocks until current phase completes (public member function)
arrive_and_drop	decrements both the initial expected count for subsequent phases and the expected count for current phase by one (public member function)
Constants
max [static]	the maximum value of expected count supported by the implementation (public static member function)

See also

latch (C++20)

single-use thread barrier (class)