|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QSystemSemaphore
public class QSystemSemaphore
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
.
When using this class, be aware of the following platform differences:
access mode
as Open
, its initial resource count will not be reset to the one provided but remain set to the value it received in the crashed process. To protect against this, the first process to create a semaphore for a particular key (usually a server), must pass its access mode
as Create
, which will force Unix to reset the resource count in the underlying system semaphore.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 == 3A typical application of system semaphores is for controlling access to a circular buffer shared by a producer process and a consumer processes.
See also QSharedMemory, 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.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 |
---|
public QSystemSemaphore(java.lang.String key, int initialValue)
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.
acquire()
, and key()
.
public QSystemSemaphore(java.lang.String key)
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.
acquire()
, and key()
.
public QSystemSemaphore(java.lang.String key, int initialValue, QSystemSemaphore.AccessMode mode)
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.
acquire()
, and key()
.
Method Detail |
---|
public final boolean acquire()
If false is returned, a system error has occurred.
release()
.
public final QSystemSemaphore.SystemSemaphoreError error()
errorString()
.
public final java.lang.String errorString()
error()
returns an error value
, call this function to get a text string that describes the error. error()
.
public final java.lang.String key()
setKey()
.
public final boolean release()
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 resourcesThis function can also "create" resources. For example, immediately following the sequence of statements above, suppose we add the statement:
sem.release(10); // "create" 10 new resourcesTen 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.
acquire()
.
public final boolean release(int n)
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 resourcesThis function can also "create" resources. For example, immediately following the sequence of statements above, suppose we add the statement:
sem.release(10); // "create" 10 new resourcesTen 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.
acquire()
.
public final void setKey(java.lang.String key, int initialValue)
key()
.
public final void setKey(java.lang.String key)
key()
.
public final void setKey(java.lang.String key, int initialValue, QSystemSemaphore.AccessMode mode)
key()
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |