Contents

• Public Types
• Public Functions
• Detailed Description
• Platform-Specific Behavior

Detailed Description

TheQSystemSemaphore 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 counterpartQSemaphore, aQSystemSemaphore can be accessed from multiplethreads. UnlikeQSemaphore, aQSystemSemaphore can also be accessed from multipleprocesses. This meansQSystemSemaphore is a much heavier class, so if your application doesn't need to access your semaphores across multiple processes, you will probably want to useQSemaphore.

Semaphores support two fundamental operations,acquire() andrelease():

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

QSystemSemaphore sem("market",3,QSystemSemaphore::Create);// resources available == 3sem.acquire();// resources available == 2sem.acquire();// resources available == 1sem.acquire();// resources available == 0sem.release();// resources available == 1sem.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 ofQSystemSemaphore 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:

• QSystemSemaphore owns the underlying system semaphore in Unix systems. This means that the last process having an instance ofQSystemSemaphore for a particular key must remove the underlying system semaphore in its destructor. If the last process crashes without running theQSystemSemaphore destructor, Unix does not automatically remove the underlying system semaphore, and the semaphore survives the crash. A subsequent process that constructs aQSystemSemaphore with the same key will then be given the existing system semaphore. In that case, if theQSystemSemaphore constructor has specified itsaccess mode asOpen, 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 itsaccess mode asCreate, which will force Unix to reset the resource count in the underlying system semaphore.
• When a process usingQSystemSemaphore terminates for any reason, Unix automatically reverses the effect of all acquire operations that were not released. Thus if the process acquires a resource and then exits without releasing it, Unix will release that resource.
• Symbian:QSystemSemaphore behaves the same as Windows semaphores. In other words, the operating system owns the semaphore and ignoresQSystemSemaphore::AccessMode.

Member Type Documentation

enum QSystemSemaphore::AccessMode

This enum is used by the constructor andsetKey(). Its purpose is to enable handling the problem in Unix implementations of semaphores that survive a crash. In Unix, when a semaphore survives a crash, we need a way to force it to reset its resource count, when the system reuses the semaphore. In Windows and in Symbian, where semaphores can't survive a crash, this enum has no effect.

enum QSystemSemaphore::SystemSemaphoreError

Member Function Documentation

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

Requests a system semaphore for the specifiedkey. The parametersinitialValue andmode are used according to the following rules, which are system dependent.

In Unix, if themode isOpen and the system already has a semaphore identified bykey, 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 bykey, it creates a new semaphore for that key and sets its resource count toinitialValue.

In Unix, if themode isCreate and the system already has a semaphore identified bykey, that semaphore is used, and its resource count is set toinitialValue. If the system does not already have a semaphore identified bykey, it creates a new semaphore for that key and sets its resource count toinitialValue.

In QNX, if themode isCreate and the system already has a semaphore identified bykey, that semaphore will be deleted and the new one will be created for that key with a resource count set toinitialValue.

In Windows and in Symbian,mode is ignored, and the system always tries to create a semaphore for the specifiedkey. If the system does not already have a semaphore identified askey, it creates the semaphore and sets its resource count toinitialValue. But if the system already has a semaphore identified askey it uses that semaphore and ignoresinitialValue.

Themode 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 samekey will get the semaphore that survived the crash, and unlessmode isCreate, the resource count will not be reset toinitialValue but will retain the initial value it had been given by the crashed process.

See alsoacquire() andkey().

QSystemSemaphore::~QSystemSemaphore()

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

Two important side effects of the destructor depend on the system. In Windows, ifacquire() has been called for this semaphore but notrelease(),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. Callerror() to get a value ofQSystemSemaphore::SystemSemaphoreError that indicates which error occurred.

See alsorelease().

SystemSemaphoreError QSystemSemaphore::error() const

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

See alsoerrorString().

QString QSystemSemaphore::errorString() const

Returns a text description of the last error that occurred. Iferror() returns anerror value, call this function to get a text string that describes the error.

See alsoerror().

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

bool QSystemSemaphore::release(int n = 1)

Releasesn 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);sem.acquire(5);// acquire all 5 resourcessem.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 alsoacquire().

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

This function works the same as the constructor. It reconstructs thisQSystemSemaphore object. If the newkey 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 newkey. TheinitialValue andmode parameters are as defined for the constructor.

See alsoQSystemSemaphore() andkey().