Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.core
Class QSemaphore

    java.lang.Object
      com.trolltech.qt.internal.QSignalEmitterInternal
          com.trolltech.qt.QSignalEmitter
              com.trolltech.qt.QtJambiObject
                  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()`:

- 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 = 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.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()`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD