QSemaphore Class | Qt Core 6.4.3

- Qt 6.4
- Qt Core
- C++ Classes
- QSemaphore
- Qt 6.4.3 Reference Documentation

# QSemaphore Class

The QSemaphore class provides a general counting semaphore. More...

Header: | #include <QSemaphore>
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: | QT += core

- List of all members, including inherited members

Note: All functions in this class are thread-safe.

## 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, std::chrono::duration<Rep, Period> timeout)
bool | try_acquire()
bool | try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)
bool | try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)

## Detailed Description

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

### 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().

### 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)

Tries to acquire `n` resources guarded by the semaphore and returns `true` on success. If available() < n, this call will wait for at most timeout milliseconds for resources to become available.

Note: Passing a negative number as the timeout is equivalent to calling acquire(), i.e. this function will wait forever for resources to become available if timeout is negative.

Example:

     QSemaphore sem(5);            // sem.available() == 5
     sem.tryAcquire(250, 1000);    // sem.available() == 5, waits 1000 milliseconds and returns false
     sem.tryAcquire(3, 30000);     // sem.available() == 2, returns true without waiting

See also acquire().

### `[since 6.3]` template <typename Rep, typename Period> bool QSemaphore::tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)

This is an overloaded function.

This function was introduced in Qt 6.3.

### `[since 6.3]` bool QSemaphore::try_acquire()

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.

This function was introduced in Qt 6.3.

See also tryAcquire(), try_acquire_for(), and try_acquire_until().

### `[since 6.3]` template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)

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.

This function was introduced in Qt 6.3.

See also tryAcquire(), try_acquire(), and try_acquire_until().

### `[since 6.3]` template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)

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.

This function was introduced in Qt 6.3.

See also tryAcquire(), try_acquire(), and try_acquire_for().