\inmodule QtCore More...

#include <qsemaphore.h>

Collaboration diagram for QSemaphore:

Public Member Functions
	QSemaphore (int n=0)
	Creates a new semaphore and initializes the number of resources it guards to n (by default, 0).

	~QSemaphore ()
	Destroys the semaphore.

void	acquire (int n=1)
	Tries to acquire `n` resources guarded by the semaphore.

bool	tryAcquire (int n=1)
	Tries to acquire `n` resources guarded by the semaphore and returns `true` on success.

bool	tryAcquire (int n, int timeout)
	Tries to acquire `n` resources guarded by the semaphore and returns `true` on success.

bool	tryAcquire (int n, QDeadlineTimer timeout)

void	release (int n=1)
	Releases n resources guarded by the semaphore.

int	available () const
	Returns the number of resources currently available to the semaphore.

bool	try_acquire () noexcept

template<typename Rep , typename Period >
bool	try_acquire_for (const std::chrono::duration< Rep, Period > &timeout)

template<typename Clock , typename Duration >
bool	try_acquire_until (const std::chrono::time_point< Clock, Duration > &tp)

Detailed Description

\inmodule QtCore

The QSemaphore class provides a general counting semaphore.

\threadsafe

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():

\list

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. \endlist

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 \l{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, {Semaphores Example}

Definition at line 15 of file qsemaphore.h.

Constructor & Destructor Documentation

◆ QSemaphore()

QSemaphore::QSemaphore ( int n = 0 )

explicit

Creates a new semaphore and initializes the number of resources it guards to n (by default, 0).

See also: release(), available()

Definition at line 284 of file qsemaphore.cpp.

References d, QtFreeBSDFutex::futexAvailable(), futexHasWaiterCount, Q_ASSERT_X, QBasicAtomicInteger< T >::storeRelaxed(), and u.

Here is the call graph for this function:

◆ ~QSemaphore()

QSemaphore::~QSemaphore ( )

Destroys the semaphore.

Warning: Destroying a semaphore that is in use may result in undefined behavior.

Definition at line 303 of file qsemaphore.cpp.

References d, and QtFreeBSDFutex::futexAvailable().

Here is the call graph for this function:

Member Function Documentation

◆ acquire()

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(), tryAcquire()

Definition at line 316 of file qsemaphore.cpp.

References d, QDeadlineTimer::Forever, QtFreeBSDFutex::futexAvailable(), futexSemaphoreTryAcquire(), Q_ASSERT_X, and u.

Referenced by ActiveCamera::~ActiveCamera(), QImage::applyColorTransform(), convert_generic(), convert_generic_inplace(), convert_generic_inplace_over_rgb64(), convert_generic_over_rgb64(), doActivate(), QMetaMethodInvoker::invokeImpl(), multithread_pixels_function(), QAndroidEventDispatcher::processEvents(), QLibProxyWrapper::run(), org.qtproject.qt.android.QtThread::run(), ActiveCamera::setFormat(), and QtConcurrent::ThreadEngineBarrier::wait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ available()

int QSemaphore::available ( ) const

Returns the number of resources currently available to the semaphore.

This number can never be negative.

See also: acquire(), release()

Definition at line 414 of file qsemaphore.cpp.

References d, QtFreeBSDFutex::futexAvailable(), futexAvailCounter(), QBasicAtomicInteger< T >::loadRelaxed(), and u.

Here is the call graph for this function:

◆ 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 \l{http://en.cppreference.com/w/cpp/language/raii}{RAII} wrapper around this function.

See also: acquire(), available(), QSemaphoreReleaser

Definition at line 350 of file qsemaphore.cpp.

References d, QtFreeBSDFutex::futexAvailable(), futexHasWaiterCount, futexHigh32(), futexLow32(), futexNeedsWake(), futexNeedsWakeAllBit, QtFreeBSDFutex::futexWakeAll(), QBasicAtomicInteger< T >::loadRelaxed(), Q_ASSERT_X, QBasicAtomicInteger< T >::testAndSetRelease(), and u.

Referenced by QLibProxyWrapper::~QLibProxyWrapper(), QSemaphoreReleaser::~QSemaphoreReleaser(), QImage::applyColorTransform(), convert_generic(), convert_generic_inplace(), convert_generic_inplace_over_rgb64(), convert_generic_over_rgb64(), QLibProxyWrapper::getProxies(), multithread_pixels_function(), ActiveCamera::onFlush(), QtConcurrent::ThreadEngineBarrier::release(), org.qtproject.qt.android.QtThread::run(), and QAndroidEventDispatcher::start().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ try_acquire()

bool QSemaphore::try_acquire ( )

inlinenoexcept

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(), try_acquire_until()

Definition at line 37 of file qsemaphore.h.

References tryAcquire().

Here is the call graph for this function:

◆ try_acquire_for()

template<typename Rep , typename Period >

template< typename Rep, typename Period > bool QSemaphore::try_acquire_for ( const std::chrono::duration< Rep, Period > & timeout )

inline

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(), try_acquire_until()

Definition at line 39 of file qsemaphore.h.

References tryAcquire().

Here is the call graph for this function:

◆ try_acquire_until()

template<typename Clock , typename Duration >

template< typename Clock, typename Duration > bool QSemaphore::try_acquire_until ( const std::chrono::time_point< Clock, Duration > & tp )

inline

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(), try_acquire_for()

Definition at line 42 of file qsemaphore.h.

◆ tryAcquire() [1/3]

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

References tryAcquire().

Here is the call graph for this function:

◆ tryAcquire() [2/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()

Definition at line 480 of file qsemaphore.cpp.

References acquire(), d, QtFreeBSDFutex::futexAvailable(), futexSemaphoreTryAcquire(), Q_ASSERT_X, timer, tryAcquire(), and u.

Here is the call graph for this function:

◆ tryAcquire() [3/3]

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