QSemaphore Class
The QSemaphore class provides a general counting semaphore. More...
Header: | #include <QSemaphore> |
Public Functions
QSemaphore(int n = 0) | |
~QSemaphore() | |
void | acquire(int n = 1) |
int | available() const |
void | release(int n = 1) |
bool | tryAcquire(int n = 1) |
bool | tryAcquire(int n, int timeout) |
bool | tryAcquire(int n, QDeadlineTimer timer) |
bool | try_acquire() |
bool | try_acquire_for(const int &timeout) |
bool | try_acquire_until(const int &tp) |
Detailed Description
\inmodule
QtCore
\threadsafe
\ingroup
thread
A semaphore is a generalization of a mutex. While a mutex can only be locked once, it's possible to acquire a semaphore multiple times. Semaphores are typically used to protect a certain number of identical resources.
Semaphores support two fundamental operations, acquire() and release():
- acquire(n) tries to acquire n resources. If there aren't that many resources available, the call will block until this is the case.
- release(n) releases n resources.
There's also a tryAcquire() function that returns immediately if it cannot acquire the resources, and an available() function that returns the number of available resources at any time.
Example:
QSemaphore sem(5); // sem.available() == 5 sem.acquire(3); // sem.available() == 2 sem.acquire(2); // sem.available() == 0 sem.release(5); // sem.available() == 5 sem.release(5); // sem.available() == 10 sem.tryAcquire(1); // sem.available() == 9, returns true sem.tryAcquire(250); // sem.available() == 9, returns false
A typical application of semaphores is for controlling access to a circular buffer shared by a producer thread and a consumer thread. The Semaphores Example shows how to use QSemaphore to solve that problem.
A non-computing example of a semaphore would be dining at a restaurant. A semaphore is initialized with the number of chairs in the restaurant. As people arrive, they want a seat. As seats are filled, available() is decremented. As people leave, the available() is incremented, allowing more people to enter. If a party of 10 people want to be seated, but there are only 9 seats, those 10 people will wait, but a party of 4 people would be seated (taking the available seats to 5, making the party of 10 people wait longer).
See also QSemaphoreReleaser, QMutex, QWaitCondition, QThread, and Semaphores Example.
Member Function Documentation
[explicit]
QSemaphore::QSemaphore(int n = 0)
Creates a new semaphore and initializes the number of resources it guards to n (by default, 0).
See also release() and available().
[noexcept]
QSemaphore::~QSemaphore()
Destroys the semaphore.
Warning: Destroying a semaphore that is in use may result in undefined behavior.
void QSemaphore::acquire(int n = 1)
Tries to acquire n
resources guarded by the semaphore. If n > available(), this call will block until enough resources are available.
See also release(), available(), and tryAcquire().
int QSemaphore::available() const
Returns the number of resources currently available to the semaphore. This number can never be negative.
See also acquire() and release().
void QSemaphore::release(int n = 1)
Releases n resources guarded by the semaphore.
This function can be used to "create" resources as well. For example:
QSemaphore sem(5); // a semaphore that guards 5 resources sem.acquire(5); // acquire all 5 resources sem.release(5); // release the 5 resources sem.release(10); // "create" 10 new resources
QSemaphoreReleaser is a RAII wrapper around this function.
See also acquire(), available(), and QSemaphoreReleaser.
bool QSemaphore::tryAcquire(int n = 1)
Tries to acquire n
resources guarded by the semaphore and returns true
on success. If available() < n, this call immediately returns false
without acquiring any resources.
Example:
QSemaphore sem(5); // sem.available() == 5 sem.tryAcquire(250); // sem.available() == 5, returns false sem.tryAcquire(3); // sem.available() == 2, returns true
See also acquire().
bool QSemaphore::tryAcquire(int n, int timeout)
This is an overloaded function.
\since
6.3
bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)
\since
6.6
Tries to acquire n
resources guarded by the semaphore and returns true
on success. If available() < n, this call will wait until timer expires for resources to become available.
Example:
QSemaphore sem(5); // sem.available() == 5 sem.tryAcquire(250, QDeadlineTimer(1000)); // sem.available() == 5, waits 1000 milliseconds and returns false sem.tryAcquire(3, QDeadlineTimer(30s)); // sem.available() == 2, returns true without waiting
See also acquire().
[noexcept]
bool QSemaphore::try_acquire()
\since
6.3
This function is provided for std::counting_semaphore
compatibility.
It is equivalent to calling tryAcquire(1)
, where the function returns true
on acquiring the resource successfully.
See also tryAcquire(), try_acquire_for(), and try_acquire_until().
template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const int &timeout)
\since
6.3
This function is provided for std::counting_semaphore
compatibility.
It is equivalent to calling tryAcquire(1, timeout)
, where the call times out on the given timeout value. The function returns true
on acquiring the resource successfully.
See also tryAcquire(), try_acquire(), and try_acquire_until().
template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const int &tp)
\since
6.3
This function is provided for std::counting_semaphore
compatibility.
It is equivalent to calling tryAcquire(1, tp - Clock::now())
, which means that the tp (time point) is recorded, ignoring the adjustments to Clock
while waiting. The function returns true
on acquiring the resource successfully.
See also tryAcquire(), try_acquire(), and try_acquire_for().