QSystemSemaphore Class

Member Function Documentation

QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)

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

The destructor destroys the QSystemSemaphore object, but the underlying system semaphore is not removed from the system unless this instance of QSystemSemaphore is the last one existing for that system semaphore.

Two important side effects of the destructor depend on the system. In Windows, if acquire() has been called for this semaphore but not release(), release() will not be called by the destructor, nor will the resource be released when the process exits normally. This would be a program bug which could be the cause of a deadlock in another process trying to acquire the same resource. In Unix, acquired resources that are not released before the destructor is called are automatically released when the process exits.

bool QSystemSemaphore::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().

QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const

Returns a value indicating whether an error occurred, and, if so, which error it was.

See also errorString().

QString QSystemSemaphore::errorString() const

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

QString QSystemSemaphore::key() const

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

bool QSystemSemaphore::release(int n = 1)

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.

QSystemSemaphore sem("market", 5, QSystemSemaphore::Create);
for (int i = 0; i < 5; ++i)  // acquire all 5 resources
    sem.acquire();
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:

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

void QSystemSemaphore::setKey(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)

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