Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/thread/counting semaphore"

From cppreference.com
< cpp‎ | thread
m (use PascalCase for template parameters consistently)
m (+exposition-only member counter)
 
(25 intermediate revisions by 12 users not shown)
Line 1: Line 1:
−
{{cpp/title|counting_semaphore}}
+
{{cpp/title|counting_semaphore|binary_semaphore}}
 
{{cpp/thread/counting_semaphore/navbar}}
 
{{cpp/thread/counting_semaphore/navbar}}
−
{{ddcl | header=semaphore | since=c++20 | 1=
+
{{dcl begin}}
−
template<std::ptrdiff_t LeastMaxValue = /* implementation-defined */>
+
{{dcl header|semaphore}}
 +
{{dcl|num=1|since=c++20|1=
 +
template< std::ptrdiff_t LeastMaxValue = /* implementation-defined */ >
 
class counting_semaphore;
 
class counting_semaphore;
 
}}
 
}}
 +
{{dcl|num=2|since=c++20|1=
 +
using binary_semaphore = std::counting_semaphore<1>;
 +
}}
 +
{{dcl end}}
  
−
A {{tt|counting_semaphore}} is a lightweight synchronization primitive that can control access to a shared resource. Unlike a {{lc|std::mutex}}, a {{tt|counting_semaphore}} allows more than one concurrent access to the same resource, for at least {{tt|LeastMaxValue}} concurrent accessors.
+
@1@ A {{tt|counting_semaphore}} is a lightweight synchronization primitive that can control access to a shared resource. Unlike a {{lc|std::mutex}}, a {{tt|counting_semaphore}} allows more than one concurrent access to the same resource, for at least {{tt|LeastMaxValue}} concurrent accessors. The program is ill-formed if {{tt|LeastMaxValue}} is negative.
  
−
Furthermore, unlike {{lc|std::mutex}} a {{tt|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 {{tt|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.
+
@2@ {{tt|binary_semaphore}} is an alias for specialization of {{tt|std::counting_semaphore}} with {{tt|LeastMaxValue}} being {{c|1}}. Implementations may implement {{tt|binary_semaphore}} more efficiently than the default implementation of {{tt|std::counting_semaphore}}.
  
−
A {{tt|counting_semaphore}} contains an internal counter initialized by the constructor. This counter is decremented by calls to {{c|acquire()}} and related methods, and is incremented by calls to {{c|release()}}. When the counter is zero, {{c|acquire()}} blocks until the counter is decremented, but {{c|try_acquire()}} does not block; {{c|try_acquire_for()}} and {{c|try_acquire_until()}} block until the counter is decremented or a timeout is reached.
+
A {{tt|counting_semaphore}} contains an internal counter initialized by the constructor. This counter is decremented by calls to {{lc|acquire()}} and related methods, and is incremented by calls to {{lc|release()}}. When the counter is zero, {{lc|acquire()}} blocks until the counter is incremented, but {{lc|try_acquire()}} does not block; {{lc|try_acquire_for()}} and {{lc|try_acquire_until()}} block until the counter is incremented or a timeout is reached.
  
−
Similar to {{lc|std::condition_variable}}'s {{c|wait()}}, {{tt|counting_semaphore}}'s {{c|try_acquire()}} can spuriously fail and should be used with care.
+
Similar to {{lc|std::condition_variable::wait()}}, {{tt|counting_semaphore}}'s {{lc|try_acquire()}} can spuriously fail.
  
−
The template class {{tt|std::counting_semaphore}} is not {{named req|DefaultConstructible}}, {{named req|CopyConstructible}}, {{named req|MoveConstructible}}, {{named req|CopyAssignable}}, or {{named req|MoveAssignable}}.
+
Specializations of {{tt|std::counting_semaphore}} are not {{named req|DefaultConstructible}}, {{named req|CopyConstructible}}, {{named req|MoveConstructible}}, {{named req|CopyAssignable}}, or {{named req|MoveAssignable}}.
 +
 
 +
===Data Members===
 +
{{dsc begin}}
 +
{{dsc hitem|Member name|Definition}}
 +
{{dsc expos mem obj|counter|private=yes|The internal counter of type {{lc|std::ptrdiff_t}}.}}
 +
{{dsc end}}
  
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc constructor | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc constructor}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc destructor | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc destructor}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc operator{{=}} | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc operator{{=}}}}
  
−
{{dsc h2 | Operations}}
+
{{dsc h2|Operations}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc release | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc release}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc acquire | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc acquire}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc try_acquire | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc try_acquire}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc try_acquire_for | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc try_acquire_for}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc try_acquire_until | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc try_acquire_until}}
  
−
{{dsc h1 | Constants}}
+
{{dsc h2|Constants}}
−
{{dsc inc | cpp/thread/counting_semaphore/dsc max | counting_semaphore}}
+
{{dsc inc|cpp/thread/counting_semaphore/dsc max}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Notes===
 
===Notes===
−
# The non-type template parameter {{tt|LeastMaxValue}} must be non-negative.
+
As its name indicates, the {{tt|LeastMaxValue}} is the ''minimum'' max value, not the ''actual'' max value. Thus {{lc|max()}} can yield a number larger than {{tt|LeastMaxValue}}.
−
# As its name indicates, the {{tt|LeastMaxValue}} is the ''minimum'' max value, not the ''actual'' max value. Thus {{c|max()}} can yield a number larger than {{tt|LeastMaxValue}}, and should be used with care.
+
 
−
# Semaphores are also often used for the semantics of signalling/notifying rather than mutual exclusion, by initializing the semaphore with {{c|0}} and thus blocking the receiver(s) that try to {{c|acquire()}}, until the notifier "signals" by invoking {{c|release(n)}}. In this respect semaphores can be considered alternatives to {{lc|std::condition_variable}}s, often with better performance. A semaphore has no shared variable, however, unlike {{lc|std::condition_variable}}.
+
Unlike {{lc|std::mutex}} a {{tt|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 {{tt|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 {{lc|std::binary_semaphore}} is an alias for {{tt|counting_semaphore<1>}}, but is documented separately.
+
 
 +
Semaphores are also often used for the semantics of signaling/notifying rather than mutual exclusion, by initializing the semaphore with {{c|0}} and thus blocking the receiver(s) that try to {{lc|acquire()}}, until the notifier "signals" by invoking {{c|release(n)}}. In this respect semaphores can be considered alternatives to {{lc|std::condition_variable}}s, often with better performance.
 +
 
 +
{{feature test macro|__cpp_lib_semaphore|{{tt|std::counting_semaphore}}, {{tt|std::binary_semaphore}}|std=C++20|value=201907L}}
  
 
===Example===
 
===Example===
−
{{example}}
+
{{example
 +
|
 +
|code=
 +
#include <chrono>
 +
#include <iostream>
 +
#include <semaphore>
 +
#include <thread>
 +
 
 +
// global binary semaphore instances
 +
// object counts are set to zero
 +
// objects are in non-signaled state
 +
std::binary_semaphore
 +
    smphSignalMainToThread{0},
 +
    smphSignalThreadToMain{0};
 +
 
 +
void ThreadProc()
 +
{
 +
    // wait for a signal from the main proc
 +
    // by attempting to decrement the semaphore
 +
    smphSignalMainToThread.acquire();
 +
 
 +
    // this call blocks until the semaphore's count
 +
    // is increased from the main proc
 +
 
 +
    std::cout << "[thread] Got the signal\n"; // response message
 +
 
 +
    // wait for 3 seconds to imitate some work
 +
    // being done by the thread
 +
    using namespace std::literals;
 +
    std::this_thread::sleep_for(3s);
 +
 
 +
    std::cout << "[thread] Send the signal\n"; // message
 +
 
 +
    // signal the main proc back
 +
    smphSignalThreadToMain.release();
 +
}
 +
 
 +
int main()
 +
{
 +
    // create some worker thread
 +
    std::thread thrWorker(ThreadProc);
 +
 
 +
    std::cout << "[main] Send the signal\n"; // message
 +
 
 +
    // signal the worker thread to start working
 +
    // by increasing the semaphore's count
 +
    smphSignalMainToThread.release();
 +
 
 +
    // wait until the worker thread is done doing the work
 +
    // by attempting to decrement the semaphore's count
 +
    smphSignalThreadToMain.acquire();
 +
 
 +
    std::cout << "[main] Got the signal\n"; // response message
 +
    thrWorker.join();
 +
}
 +
|output=
 +
[main] Send the signal
 +
[thread] Got the signal
 +
[thread] Send the signal
 +
[main] Got the signal
 +
}}
  
−
{{langlinks|ja|zh}}
+
{{langlinks|es|ja|ru|zh}}

Latest revision as of 12:13, 19 May 2024

 
C++
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++17)(C++17)
this_thread namespace
(C++11)
(C++11)
(C++11)
(C++11)
Cooperative cancellation
Mutual exclusion
(C++11)
(C++11)
(C++17)
Generic lock management
(C++11)
(C++11)
(C++17)
(C++11)
(C++14)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)
Condition variables
(C++11)
(C++11)
(C++11)
(C++11)
Semaphores
counting_semaphorebinary_semaphore
(C++20)(C++20)
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
(C++26)
(C++26)
(C++26)
Hazard Pointers
(C++26)
(C++26)
(C++26)
Atomic types
(C++11)
(C++20)
(C++11)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)
Memory ordering
(C++11)
(C++11)
(C++11)
(C++11)
Free functions for atomic operations
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++26)(C++26)
(C++26)(C++26)
(C++11)
(C++20)(C++20)
(C++20)
(C++20)
Free functions for atomic flags
(C++11)(C++11)
(C++11)(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
 
std::counting_semaphore
 
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. The program is ill-formed if LeastMaxValue is negative.
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.

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 incremented, but try_acquire() does not block; try_acquire_for() and try_acquire_until() block until the counter is incremented or a timeout is reached.

Similar to std::condition_variable::wait(), counting_semaphore's try_acquire() can spuriously fail.

Specializations of std::counting_semaphore are not DefaultConstructible, CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable.

Contents

[edit] Data Members

Member name Definition
counter (private) The internal counter of type std::ptrdiff_t.
(exposition-only member object*)

[edit] Member functions

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

[edit] Notes

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.

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.

Semaphores are also often used for the semantics of signaling/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.

Feature-test macro Value Std Feature
__cpp_lib_semaphore 201907L (C++20) std::counting_semaphore, std::binary_semaphore

[edit] Example

Run this code
#include <chrono>
#include <iostream>
#include <semaphore>
#include <thread>
 
// global binary semaphore instances
// object counts are set to zero
// objects are in non-signaled state
std::binary_semaphore
    smphSignalMainToThread{0},
    smphSignalThreadToMain{0};
 
void ThreadProc()
{
    // wait for a signal from the main proc
    // by attempting to decrement the semaphore
    smphSignalMainToThread.acquire();
 
    // this call blocks until the semaphore's count
    // is increased from the main proc
 
    std::cout << "[thread] Got the signal\n"; // response message
 
    // wait for 3 seconds to imitate some work
    // being done by the thread
    using namespace std::literals;
    std::this_thread::sleep_for(3s);
 
    std::cout << "[thread] Send the signal\n"; // message
 
    // signal the main proc back
    smphSignalThreadToMain.release();
}
 
int main()
{
    // create some worker thread
    std::thread thrWorker(ThreadProc);
 
    std::cout << "[main] Send the signal\n"; // message
 
    // signal the worker thread to start working
    // by increasing the semaphore's count
    smphSignalMainToThread.release();
 
    // wait until the worker thread is done doing the work
    // by attempting to decrement the semaphore's count
    smphSignalThreadToMain.acquire();
 
    std::cout << "[main] Got the signal\n"; // response message
    thrWorker.join();
}

Output: 

[main] Send the signal
[thread] Got the signal
[thread] Send the signal
[main] Got the signal
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/thread/counting_semaphore&oldid=171868"