com.trolltech.qt.core
Class QSemaphore

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QSemaphore
All Implemented Interfaces:
QtJambiInterface

public class QSemaphore
extends QtJambiObject

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

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 = new QSemaphore(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.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QSemaphore()
          Creates a new semaphore and initializes the number of resources it guards to n (by default, 0).
QSemaphore(int n)
          Creates a new semaphore and initializes the number of resources it guards to n (by default, 0).
 
Method Summary
 void acquire()
          Tries to acquire n resources guarded by the semaphore.
 void acquire(int n)
          Tries to acquire n resources guarded by the semaphore.
 int available()
          Returns the number of resources currently available to the semaphore.
 void release()
          Releases n resources guarded by the semaphore.
 void release(int n)
          Releases n resources guarded by the semaphore.
 boolean tryAcquire()
          Tries to acquire n resources guarded by the semaphore and returns true on success.
 boolean tryAcquire(int n)
          Tries to acquire n resources guarded by the semaphore and returns true on success.
 boolean tryAcquire(int n, int timeout)
          Tries to acquire n resources guarded by the semaphore and returns true on success.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QSemaphore

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

See also:
release(), and available().


QSemaphore

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

See also:
release(), and available().

Method Detail

acquire

public final void acquire()
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().


acquire

public final void acquire(int n)
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().


available

public final int available()
Returns the number of resources currently available to the semaphore. This number can never be negative.

See also:
acquire(), and release().


release

public final void release()
Releases n resources guarded by the semaphore.

This function can be used to "create" resources as well. For example:

        QSemaphore sem = new QSemaphore(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(), and available().


release

public final void release(int n)
Releases n resources guarded by the semaphore.

This function can be used to "create" resources as well. For example:

        QSemaphore sem = new QSemaphore(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(), and available().


tryAcquire

public final boolean tryAcquire()
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 = new QSemaphore(5);      // sem.available() == 5
        sem.tryAcquire(250);    // sem.available() == 5, returns false
        sem.tryAcquire(3);      // sem.available() == 2, returns true

See also:
acquire().


tryAcquire

public final boolean tryAcquire(int n)
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 = new QSemaphore(5);      // sem.available() == 5
        sem.tryAcquire(250);    // sem.available() == 5, returns false
        sem.tryAcquire(3);      // sem.available() == 2, returns true

See also:
acquire().


tryAcquire

public final boolean 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 = new QSemaphore(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().