std::counting_semaphore, std::binary_semaphore

 

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::counting_semaphore

Member functions

counting_semaphore::counting_semaphore

counting_semaphore::~counting_semaphore

Operations

counting_semaphore::release

counting_semaphore::acquire

counting_semaphore::try_acquire

counting_semaphore::try_acquire_for

counting_semaphore::try_acquire_until

Constants

counting_semaphore::max

 

Defined in header <semaphore>
template<std::ptrdiff_t LeastMaxValue = /* implementation-defined */> class counting_semaphore;	(1)	(since C++20)
using binary_semaphore = std::counting_semaphore<1>;	(2)	(since C++20)

1) A counting_semaphore is a lightweight synchronization primitive that can control access to a shared resource. Unlike a std::mutex, a counting_semaphore allows more than one concurrent access to the same resource, for at least LeastMaxValue concurrent accessors.

2) binary_semaphore is an alias for specialization of std::counting_semaphore with LeastMaxValue being 1. Implementations may implement binary_semaphore more efficiently than the default implementation of std::counting_semaphore.

Furthermore, unlike std::mutex a counting_semaphore is not tied to threads of execution - acquiring a semaphore can occur on a different thread than releasing the semaphore, for example. All operations on counting_semaphore can be performed concurrently and without any relation to specific threads of execution, with the exception of the destructor which cannot be performed concurrently but can be performed on a different thread.

A counting_semaphore contains an internal counter initialized by the constructor. This counter is decremented by calls to acquire() and related methods, and is incremented by calls to release(). When the counter is zero, acquire() blocks until the counter is decremented, but try_acquire() does not block; try_acquire_for() and try_acquire_until() block until the counter is decremented or a timeout is reached.

Similar to std::condition_variable's wait(), counting_semaphore's try_acquire() can spuriously fail and should be used with care.

The template class std::counting_semaphore is not DefaultConstructible, CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable.

Member functions

(constructor)	constructs a counting_semaphore (public member function)
(destructor)	destructs the counting_semaphore (public member function)
operator= [deleted]	counting_semaphore is not assignable (public member function)
Operations
release	increments the internal counter and unblocks acquirers (public member function)
acquire	decrements the internal counter or blocks until it can (public member function)
try_acquire	tries to decrement the internal counter without blocking (public member function)
try_acquire_for	tries to decrement the internal counter, blocking for up to a duration time (public member function)
try_acquire_until	tries to decrement the internal counter, blocking until a point in time (public member function)
Constants
max [static]	returns the maximum possible value of the internal counter (public static member function)

Notes

1. The non-type template parameter LeastMaxValue must be non-negative.
2. As its name indicates, the LeastMaxValue is the minimum max value, not the actual max value. Thus max() can yield a number larger than LeastMaxValue, and should be used with care.
3. Semaphores are also often used for the semantics of signalling/notifying rather than mutual exclusion, by initializing the semaphore with ​0​ and thus blocking the receiver(s) that try to acquire(), until the notifier "signals" by invoking release(n). In this respect semaphores can be considered alternatives to std::condition_variables, often with better performance. A semaphore has no shared variable, however, unlike std::condition_variable.