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

#include <qsemaphore.h>

Collaboration diagram for QSemaphore:

Public Member Functions
	QSemaphore (int n=0)

	~QSemaphore ()

void	acquire (int n=1)

bool	tryAcquire (int n=1)

bool	tryAcquire (int n, int timeout)

template<typename Rep , typename Period >
bool	tryAcquire (int n, std::chrono::duration< Rep, Period > timeout)

void	release (int n=1)

int	available () const

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

The QSemaphore class provides a general counting semaphore.

\inmodule QtCore

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

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 54 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 291 of file qsemaphore.cpp.

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 310 of file qsemaphore.cpp.

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 323 of file qsemaphore.cpp.

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 418 of file qsemaphore.cpp.

Here is the call graph for this function:

Here is the caller 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:

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 351 of file qsemaphore.cpp.

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 72 of file qsemaphore.h.

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 accquiring the resource successfully.

See also: tryAcquire(), try_acquire(), try_acquire_until()

Definition at line 74 of file qsemaphore.h.

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 77 of file qsemaphore.h.

◆ tryAcquire() [1/3]

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:

See also: acquire()

Definition at line 468 of file qsemaphore.cpp.

◆ tryAcquire() [2/3]

template<typename Rep , typename Period >

template< typename Rep, typename Period > QSemaphore::tryAcquire	(	int	n,
		std::chrono::duration< Rep, Period >	timeout
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since: 6.3

Definition at line 64 of file qsemaphore.h.

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: