QSemaphore Class Reference

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

#include <qsemaphore.h>

Public Functions
void	acquire (int n=1)
	Tries to acquire n resources guarded by the semaphore. More...
int	available () const
	Returns the number of resources currently available to the semaphore. More...
	QSemaphore (int n=0)
	Creates a new semaphore and initializes the number of resources it guards to n (by default, 0). More...
void	release (int n=1)
	Releases n resources guarded by the semaphore. More...
bool	tryAcquire (int n=1)
	Tries to acquire n resources guarded by the semaphore and returns true on success. More...
bool	tryAcquire (int n, int timeout)
	Tries to acquire n resources guarded by the semaphore and returns true on success. More...
	~QSemaphore ()
	Destroys the semaphore. More...

Properties
QSemaphorePrivate *	d

Detailed Description

The QSemaphore class provides a general counting semaphore.

Note

This class or function is 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():

• 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

QMutex, QWaitCondition, QThread, {Semaphores Example}

Definition at line 57 of file qsemaphore.h.

Constructors and Destructors

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

{
    Q_ASSERT_X(n >= 0, "QSemaphore", "parameter 'n' must be non-negative");
    d = new QSemaphorePrivate(n);
}

~QSemaphore()

QSemaphore::~QSemaphore

(

)

Destroys the semaphore.

Warning

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

Definition at line 132 of file qsemaphore.cpp.

{ delete d; }

Functions

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

Referenced by Rendezvous::checkpoint(), and QFastMutex::lock().

{
    Q_ASSERT_X(n >= 0, "QSemaphore::acquire", "parameter 'n' must be non-negative");
    QMutexLocker locker(&d->mutex);
    while (n > d->avail)
        d->cond.wait(locker.mutex());
    d->avail -= n;
}

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

{
    QMutexLocker locker(&d->mutex);
    return d->avail;
}

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

See also

acquire(), available()

Definition at line 161 of file qsemaphore.cpp.

Referenced by Rendezvous::checkpoint(), QFastMutex::unlock(), and QMetaCallEvent::~QMetaCallEvent().

{
    Q_ASSERT_X(n >= 0, "QSemaphore::release", "parameter 'n' must be non-negative");
    QMutexLocker locker(&d->mutex);
    d->avail += n;
    d->cond.wakeAll();
}

tryAcquire() [1/2]

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

Definition at line 192 of file qsemaphore.cpp.

{
    Q_ASSERT_X(n >= 0, "QSemaphore::tryAcquire", "parameter 'n' must be non-negative");
    QMutexLocker locker(&d->mutex);
    if (n > d->avail)
        return false;
    d->avail -= n;
    return true;
}

tryAcquire() [2/2]

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

Definition at line 218 of file qsemaphore.cpp.

{
    Q_ASSERT_X(n >= 0, "QSemaphore::tryAcquire", "parameter 'n' must be non-negative");
    QMutexLocker locker(&d->mutex);
    if (timeout < 0) {
        while (n > d->avail)
            d->cond.wait(locker.mutex());
    } else {
        QElapsedTimer timer;
        timer.start();
        while (n > d->avail) {
            const qint64 elapsed = timer.elapsed();
            if (timeout - elapsed <= 0
                || !d->cond.wait(locker.mutex(), timeout - elapsed))
                return false;
        }
    }
    d->avail -= n;
    return true;


}

Properties

d

QSemaphorePrivate* QSemaphore::d

private

Definition at line 74 of file qsemaphore.h.

---

The documentation for this class was generated from the following files:

• /src/corelib/thread/qsemaphore.h
• /src/corelib/thread/qsemaphore.cpp