QSemaphore Class Reference
[QtCore module]

Detailed Description

The QSemaphore class provides a general counting semaphore.

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, and Semaphores Example.

Member Function Documentation

 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

 QSemaphore sem(5);      // sem.available() == 5
 sem.tryAcquire(250);    // sem.available() == 5, returns false
 sem.tryAcquire(3);      // sem.available() == 2, returns true

 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