Overview | Package | Class | Tree | Deprecated | Index | Help
Qt Jambi Home |
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.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(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`, `Example`

Nested Class Summary

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
`QSignalEmitter.AbstractSignal, QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>`

Constructor Summary
`QSemaphore()` Equivalent to `QSemaphore`(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()` Equivalent to acquire(1).
`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.
`static QSemaphore` | `fromNativePointer(QNativePointer nativePointer)` This function returns the QSemaphore instance pointed to by nativePointer
`void` | `release()` Equivalent to release(1).
`void` | `release(int n)` Releases `n` resources guarded by the semaphore.
`boolean` | `tryAcquire()` Equivalent to `tryAcquire`(1).
`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, finalize, reassignNativeResources, tr, tr, tr`

Methods inherited from class com.trolltech.qt.QSignalEmitter
`blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread`

Methods inherited from class java.lang.Object
`clone, equals, 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()

  Equivalent to `QSemaphore`(0).

### 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`, `available`

Method Detail

### acquire

    public final void acquire()

  Equivalent to acquire(1).

### 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`, `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`, `release`

### release

    public final void release()

  Equivalent to release(1).

### 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(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`

### tryAcquire

    public final boolean tryAcquire()

  Equivalent to `tryAcquire`(1).

### 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(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(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`

### fromNativePointer

    public static QSemaphore fromNativePointer(QNativePointer nativePointer)

  This function returns the QSemaphore instance pointed to by nativePointer

  Parameters:
    `nativePointer` - the QNativePointer of which object should be returned.

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