Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

QSystemMutex Class Reference
[QtBaseModule]

The QSystemMutex class provides mutual exclusion between processes. More...

    #include <QSystemMutex>

• List of all members, including inherited members

Public Functions

• QSystemMutex ( unsigned int id, bool owner )
• ~QSystemMutex ()
• unsigned int id () const
• bool isNull () const
• bool lock ( int milliSec )
• void unlock ()

Detailed Description

The QSystemMutex class provides mutual exclusion between processes.

A mutex is a synchronization tool for protecting critical sections of the code. The purpose of a QSystemMutex is to protect an object, data structure or section of code so that only one thread, or process, can access it at a time.

QSystemMutex behaves much like the QMutex class, but it also works across multiple processes (although it also works perfectly well, albeit slightly less efficiently, in a single process). In order to clean up the system resources used to coordinate cross process synchronization, one QSystemMutex instance is designated the lock "owner". This instance creates the required resources, and removes them when it is destroyed. The lock owner should always be instantiated before any others.

System locks are identified by a 32-bit integer, which allows other processes to share the same lock. While the selection of this identifier is left upto the caller, under Linux it is common to use the ftok(3) function call which uses the identity of a specified file to generate such an identifier.

    int id = (int)::ftok("/tmp/my_lock_identifier", 0);

    QSystemMutex lock(id, true);

The file passed to ftok(3) is only used to generate a unique identifier for the mutex and is otherwise unrelated to the mutx. It is possible, although bad practice due to potential unintended clashes with other applications that do the same, to simply make up a number for the mutex id.

Other applications can then easily create a non-owner reference to the mutex:

    int id = (int)::ftok("/tmp/my_lock_identifier", 0);

    QSystemMutex lock(id, false);

An ftok(3) call on the same file was used to ensure the owner and the non-owner use the same id and thus refer to the same system-global mutex.

See also QSystemReadWriteLock.

Member Function Documentation

QSystemMutex::QSystemMutex ( unsigned int id, bool owner )

Construct a system mutex from the provided id. If owner is true, the instance will create the system resources required for the mutex and will remove them when it is destructed.

QSystemMutex::~QSystemMutex ()

Destroy the mutex instance. If owner was specified in the QSystemMutex constructor, all the system resources used by this mutex will also be removed and further use of the lock by other threads or processes will fail.

unsigned int QSystemMutex::id () const

Return the id of mutex as passed to the constructor.

bool QSystemMutex::isNull () const

Return true if the mutex is invalid.

bool QSystemMutex::lock ( int milliSec )

Attempt to acquire the lock. This method will return true if the lock was successfully acquired, false otherwise.

Aquisition of the mutex may fail if:

The timeout milliSec, in milliseconds, expired.

If the caller wants to poll the mutex in a non-blocking way, it should specify a timeout of 0. If the caller would prefer to block until the mutex is acquired it should specify a timeout of -1.

Currently, only systems that support the semtimedop(2) system call can perform non-blocking, or time blocked calls. All other systems will block indefinately until the mutex is acquired, regardless of the milliSec value.

The QSystemMutex instance does not refer to a valid lock.

Callers can check for an invalid lock using the isNull() method.

void QSystemMutex::unlock ()

Release the mutex.