com.trolltech.qt.core
Class QSystemSemaphore

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.QSystemSemaphore
All Implemented Interfaces:
QtJambiInterface

public class QSystemSemaphore
extends QtJambiObject

The QSystemSemaphore class provides a general counting system semaphore. A semaphore is a generalization of a mutex. While a mutex can be locked only once, a semaphore can be acquired multiple times. Typically, a semaphore is used to protect a certain number of identical resources.

Like its lighter counterpart QSemaphore, a QSystemSemaphore can be accessed from multiple threads. Unlike QSemaphore, a QSystemSemaphore can also be accessed from multiple processes. This means QSystemSemaphore is a much heavier class, so if your application doesn't need to access your semaphores across multiple processes, you will probably want to use QSemaphore.

Semaphores support two fundamental operations, acquire() and release():

acquire() tries to acquire one resource. If there isn't a resource available, the call blocks until a resource becomes available. Then the resource is acquired and the call returns.

release() releases one resource so it can be acquired by another process. The function can also be called with a parameter n > 1, which releases n resources.

A system semaphore is created with a string key that other processes can use to use the same semaphore.

Example: Create a system semaphore

The following code example is written in c++.

QSystemSemaphore sem("market", 3, QSystemSemaphore::Create);
                             // resources available == 3
sem.acquire();               // resources available == 2
sem.acquire();               // resources available == 1
sem.acquire();               // resources available == 0
sem.release();               // resources available == 1
sem.release(2);              // resources available == 3
A typical application of system semaphores is for controlling access to a circular buffer shared by a producer process and a consumer processes.

Platform-Specific Behavior

When using this class, be aware of the following platform differences:

Windows:QSystemSemaphore does not own its underlying system semaphore. Windows owns it. This means that when all instances of QSystemSemaphore for a particular key have been destroyed, either by having their destructors called, or because one or more processes crash, Windows removes the underlying system semaphore.

Unix:

See also:
QSharedMemory, and QSemaphore.


Nested Class Summary
static class QSystemSemaphore.AccessMode
          This enum is used by the constructor and setKey().
static class QSystemSemaphore.SystemSemaphoreError
           
 
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
QSystemSemaphore(java.lang.String key)
          Requests a system semaphore for the specified key.
QSystemSemaphore(java.lang.String key, int initialValue)
          Requests a system semaphore for the specified key.
QSystemSemaphore(java.lang.String key, int initialValue, QSystemSemaphore.AccessMode mode)
          Requests a system semaphore for the specified key.
 
Method Summary
 boolean acquire()
          Acquires one of the resources guarded by this semaphore, if there is one available, and returns true.
 QSystemSemaphore.SystemSemaphoreError error()
          Returns a value indicating whether an error occurred, and, if so, which error it was.
 java.lang.String errorString()
          Returns a text description of the last error that occurred.
 java.lang.String key()
          Returns the key assigned to this system semaphore.
 boolean release()
          Releases n resources guarded by the semaphore.
 boolean release(int n)
          Releases n resources guarded by the semaphore.
 void setKey(java.lang.String key)
          This function works the same as the constructor.
 void setKey(java.lang.String key, int initialValue)
          This function works the same as the constructor.
 void setKey(java.lang.String key, int initialValue, QSystemSemaphore.AccessMode mode)
          This function works the same as the constructor.
 
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

QSystemSemaphore

public QSystemSemaphore(java.lang.String key,
                        int initialValue)
Requests a system semaphore for the specified key. The parameters initialValue and mode are used according to the following rules, which are system dependent.

In Unix, if the mode is Open and the system already has a semaphore identified by key, that semaphore is used, and the semaphore's resource count is not changed, i.e., initialValue is ignored. But if the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Unix, if the mode is Create and the system already has a semaphore identified by key, that semaphore is used, and its resource count is set to initialValue. If the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Windows, mode is ignored, and the system always tries to create a semaphore for the specified key. If the system does not already have a semaphore identified as key, it creates the semaphore and sets its resource count to initialValue. But if the system already has a semaphore identified as key it uses that semaphore and ignores initialValue.

The mode parameter is only used in Unix systems to handle the case where a semaphore survives a process crash. In that case, the next process to allocate a semaphore with the same key will get the semaphore that survived the crash, and unless mode is Create , the resource count will not be reset to initialValue but will retain the initial value it had been given by the crashed process.

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


QSystemSemaphore

public QSystemSemaphore(java.lang.String key)
Requests a system semaphore for the specified key. The parameters initialValue and mode are used according to the following rules, which are system dependent.

In Unix, if the mode is Open and the system already has a semaphore identified by key, that semaphore is used, and the semaphore's resource count is not changed, i.e., initialValue is ignored. But if the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Unix, if the mode is Create and the system already has a semaphore identified by key, that semaphore is used, and its resource count is set to initialValue. If the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Windows, mode is ignored, and the system always tries to create a semaphore for the specified key. If the system does not already have a semaphore identified as key, it creates the semaphore and sets its resource count to initialValue. But if the system already has a semaphore identified as key it uses that semaphore and ignores initialValue.

The mode parameter is only used in Unix systems to handle the case where a semaphore survives a process crash. In that case, the next process to allocate a semaphore with the same key will get the semaphore that survived the crash, and unless mode is Create , the resource count will not be reset to initialValue but will retain the initial value it had been given by the crashed process.

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


QSystemSemaphore

public QSystemSemaphore(java.lang.String key,
                        int initialValue,
                        QSystemSemaphore.AccessMode mode)
Requests a system semaphore for the specified key. The parameters initialValue and mode are used according to the following rules, which are system dependent.

In Unix, if the mode is Open and the system already has a semaphore identified by key, that semaphore is used, and the semaphore's resource count is not changed, i.e., initialValue is ignored. But if the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Unix, if the mode is Create and the system already has a semaphore identified by key, that semaphore is used, and its resource count is set to initialValue. If the system does not already have a semaphore identified by key, it creates a new semaphore for that key and sets its resource count to initialValue.

In Windows, mode is ignored, and the system always tries to create a semaphore for the specified key. If the system does not already have a semaphore identified as key, it creates the semaphore and sets its resource count to initialValue. But if the system already has a semaphore identified as key it uses that semaphore and ignores initialValue.

The mode parameter is only used in Unix systems to handle the case where a semaphore survives a process crash. In that case, the next process to allocate a semaphore with the same key will get the semaphore that survived the crash, and unless mode is Create , the resource count will not be reset to initialValue but will retain the initial value it had been given by the crashed process.

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

Method Detail

acquire

public final boolean acquire()
Acquires one of the resources guarded by this semaphore, if there is one available, and returns true. If all the resources guarded by this semaphore have already been acquired, the call blocks until one of them is released by another process or thread having a semaphore with the same key.

If false is returned, a system error has occurred. Call error() to get a value of QSystemSemaphore::SystemSemaphoreError that indicates which error occurred.

See also:
release().


error

public final QSystemSemaphore.SystemSemaphoreError error()
Returns a value indicating whether an error occurred, and, if so, which error it was.

See also:
errorString().


errorString

public final java.lang.String errorString()
Returns a text description of the last error that occurred. If error() returns an error value , call this function to get a text string that describes the error.

See also:
error().


key

public final java.lang.String key()
Returns the key assigned to this system semaphore. The key is the name by which the semaphore can be accessed from other processes.

See also:
setKey().


release

public final boolean release()
Releases n resources guarded by the semaphore. Returns true unless there is a system error.

Example: Create a system semaphore having five resources; acquire them all and then release them all.

The following code example is written in c++.

QSystemSemaphore sem("market", 5, QSystemSemaphore::Create);
sem.acquire(5);           // acquire all 5 resources
sem.release(5);           // release the 5 resources
This function can also "create" resources. For example, immediately following the sequence of statements above, suppose we add the statement:

The following code example is written in c++.
sem.release(10);          // "create" 10 new resources
Ten new resources are now guarded by the semaphore, in addition to the five that already existed. You would not normally use this function to create more resources.

See also:
acquire().


release

public final boolean release(int n)
Releases n resources guarded by the semaphore. Returns true unless there is a system error.

Example: Create a system semaphore having five resources; acquire them all and then release them all.

The following code example is written in c++.

QSystemSemaphore sem("market", 5, QSystemSemaphore::Create);
sem.acquire(5);           // acquire all 5 resources
sem.release(5);           // release the 5 resources
This function can also "create" resources. For example, immediately following the sequence of statements above, suppose we add the statement:

The following code example is written in c++.
sem.release(10);          // "create" 10 new resources
Ten new resources are now guarded by the semaphore, in addition to the five that already existed. You would not normally use this function to create more resources.

See also:
acquire().


setKey

public final void setKey(java.lang.String key,
                         int initialValue)
This function works the same as the constructor. It reconstructs this QSystemSemaphore object. If the new key is different from the old key, calling this function is like calling the destructor of the semaphore with the old key, then calling the constructor to create a new semaphore with the new key. The initialValue and mode parameters are as defined for the constructor.

See also:
QSystemSemaphore(), and key().


setKey

public final void setKey(java.lang.String key)
This function works the same as the constructor. It reconstructs this QSystemSemaphore object. If the new key is different from the old key, calling this function is like calling the destructor of the semaphore with the old key, then calling the constructor to create a new semaphore with the new key. The initialValue and mode parameters are as defined for the constructor.

See also:
QSystemSemaphore(), and key().


setKey

public final void setKey(java.lang.String key,
                         int initialValue,
                         QSystemSemaphore.AccessMode mode)
This function works the same as the constructor. It reconstructs this QSystemSemaphore object. If the new key is different from the old key, calling this function is like calling the destructor of the semaphore with the old key, then calling the constructor to create a new semaphore with the new key. The initialValue and mode parameters are as defined for the constructor.

See also:
QSystemSemaphore(), and key().