Qt 4.8
Public Types | Public Functions | Properties | List of all members
QSystemSemaphore Class Reference

The QSystemSemaphore class provides a general counting system semaphore. More...

#include <qsystemsemaphore.h>

Public Types

enum  AccessMode { Open, Create }
 This enum is used by the constructor and setKey(). More...
 
enum  SystemSemaphoreError {
  NoError, PermissionDenied, KeyError, AlreadyExists,
  NotFound, OutOfResources, UnknownError
}
 

Public Functions

bool acquire ()
 Acquires one of the resources guarded by this semaphore, if there is one available, and returns true. More...
 
SystemSemaphoreError error () const
 Returns a value indicating whether an error occurred, and, if so, which error it was. More...
 
QString errorString () const
 Returns a text description of the last error that occurred. More...
 
QString key () const
 Returns the key assigned to this system semaphore. More...
 
 QSystemSemaphore (const QString &key, int initialValue=0, AccessMode mode=Open)
 Requests a system semaphore for the specified key. More...
 
bool release (int n=1)
 Releases n resources guarded by the semaphore. More...
 
void setKey (const QString &key, int initialValue=0, AccessMode mode=Open)
 This function works the same as the constructor. More...
 
 ~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. More...
 

Properties

QScopedPointer< QSystemSemaphorePrivated
 

Detailed Description

The QSystemSemaphore class provides a general counting system semaphore.

Since
4.4

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 QThread {threads}. Unlike QSemaphore, a QSystemSemaphore can also be accessed from multiple QProcess {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

// 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, QSemaphore

Definition at line 58 of file qsystemsemaphore.h.

Enumerations

◆ AccessMode

This enum is used by the constructor and setKey().

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.

  • Open If the semaphore already exists, its initial resource count is not reset. If the semaphore does not already exist, it is created and its initial resource count set.
  • Create QSystemSemaphore takes ownership of the semaphore and sets its resource count to the requested value, regardless of whether the semaphore already exists by having survived a crash. This value should be passed to the constructor, when the first semaphore for a particular key is constructed and you know that if the semaphore already exists it could only be because of a crash. In Windows and in Symbian, where a semaphore can't survive a crash, Create and Open have the same behavior.
Enumerator
Open 
Create 

Definition at line 62 of file qsystemsemaphore.h.

◆ SystemSemaphoreError

  • NoError No error occurred.
  • PermissionDenied The operation failed because the caller didn't have the required permissions.
  • KeyError The operation failed because of an invalid key.
  • AlreadyExists The operation failed because a system semaphore with the specified key already existed.
  • NotFound The operation failed because a system semaphore with the specified key could not be found.
  • OutOfResources The operation failed because there was not enough memory available to fill the request.
  • UnknownError Something else happened and it was bad.
Enumerator
NoError 
PermissionDenied 
KeyError 
AlreadyExists 
NotFound 
OutOfResources 
UnknownError 

Definition at line 68 of file qsystemsemaphore.h.

Constructors and Destructors

◆ QSystemSemaphore()

QSystemSemaphore::QSystemSemaphore ( const QString key,
int  initialValue = 0,
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 QSystemSemaphore::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 QSystemSemaphore::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 QNX, if the mode is QSystemSemaphore::Create and the system already has a semaphore identified by key, that semaphore will be deleted and the new one will be created for that key with a resource count set to initialValue.

In Windows and in Symbian, 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 QSystemSemaphore::AccessMode {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 QSystemSemaphore::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(), key()

Definition at line 178 of file qsystemsemaphore.cpp.

180 {
181  setKey(key, initialValue, mode);
182 }
QScopedPointer< QSystemSemaphorePrivate > d
void setKey(const QString &key, int initialValue=0, AccessMode mode=Open)
This function works the same as the constructor.

◆ ~QSystemSemaphore()

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.

Definition at line 199 of file qsystemsemaphore.cpp.

200 {
201  d->cleanHandle();
202 }
QScopedPointer< QSystemSemaphorePrivate > d

Functions

◆ acquire()

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

Definition at line 288 of file qsystemsemaphore.cpp.

289 {
290  return d->modifySemaphore(-1);
291 }
QScopedPointer< QSystemSemaphorePrivate > d

◆ error()

QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error ( ) const

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

See also
errorString()

Definition at line 331 of file qsystemsemaphore.cpp.

332 {
333  return d->error;
334 }
QSystemSemaphore::SystemSemaphoreError error
QScopedPointer< QSystemSemaphorePrivate > d

◆ errorString()

QString QSystemSemaphore::errorString ( ) const

Returns a text description of the last error that occurred.

If error() returns an QSystemSemaphore::SystemSemaphoreError {error value}, call this function to get a text string that describes the error.

See also
error()

Definition at line 366 of file qsystemsemaphore.cpp.

367 {
368  return d->errorString;
369 }
QScopedPointer< QSystemSemaphorePrivate > d

◆ key()

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

Definition at line 270 of file qsystemsemaphore.cpp.

Referenced by setKey().

271 {
272  return d->key;
273 }
QScopedPointer< QSystemSemaphorePrivate > d

◆ release()

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.

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:

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

Definition at line 314 of file qsystemsemaphore.cpp.

315 {
316  if (n == 0)
317  return true;
318  if (n < 0) {
319  qWarning("QSystemSemaphore::release: n is negative.");
320  return false;
321  }
322  return d->modifySemaphore(n);
323 }
Q_CORE_EXPORT void qWarning(const char *,...)
QScopedPointer< QSystemSemaphorePrivate > d

◆ setKey()

void QSystemSemaphore::setKey ( const QString key,
int  initialValue = 0,
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(), key()

Definition at line 241 of file qsystemsemaphore.cpp.

Referenced by QSystemSemaphore().

242 {
243  if (key == d->key && mode == Open)
244  return;
245  d->error = NoError;
246  d->errorString = QString();
247 #if !defined(Q_OS_WIN) && !defined(Q_OS_SYMBIAN) && !defined(QT_POSIX_IPC)
248  // optimization to not destroy/create the file & semaphore
249  if (key == d->key && mode == Create && d->createdSemaphore && d->createdFile) {
250  d->initialValue = initialValue;
251  d->unix_key = -1;
252  d->handle(mode);
253  return;
254  }
255 #endif
256  d->cleanHandle();
257  d->key = key;
258  d->initialValue = initialValue;
259  // cache the file name so it doesn't have to be generated all the time.
260  d->fileName = d->makeKeyFileName();
261  d->handle(mode);
262 }
QString makeKeyFileName() const
The QString class provides a Unicode character string.
Definition: qstring.h:83
QSystemSemaphore::SystemSemaphoreError error
QScopedPointer< QSystemSemaphorePrivate > d
HANDLE handle(QSystemSemaphore::AccessMode mode=QSystemSemaphore::Open)
QString key() const
Returns the key assigned to this system semaphore.

Properties

◆ d

QScopedPointer<QSystemSemaphorePrivate> QSystemSemaphore::d
private

Definition at line 93 of file qsystemsemaphore.h.

Referenced by acquire(), error(), errorString(), key(), release(), setKey(), and ~QSystemSemaphore().


The documentation for this class was generated from the following files: