Home · All Classes · Grouped Classes · Annotated · Functions

QSystemReadWriteLock Class Reference

The QSystemReadWriteLock class provides read-write locking between processes. More...

    #include <QSystemReadWriteLock>

Public Functions


Detailed Description

The QSystemReadWriteLock class provides read-write locking between processes.

A read-write lock is a synchronization tool for protecting resources that can be accessed for reading and writing. This type of lock is useful if you want to allow multiple threads to have simultaneous read-only access, but as soon as one thread wants to write to the resource, all other threads must be blocked until the writing is complete.

QSystemReadWriteLock behaves much like the QReadWriteLock 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 QReadWriteLock instance is designated the lock "owner". This instance creates the required system 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.

For example, to create the lock owner:

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

    QSystemReadWriteLock lock(id, true);

The file passed to ftok(3) is only used to generate a unique identifier for the lock and is otherwise unrelated to the lock. 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 lock id.

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

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

    QSystemReadWriteLock 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 lock.

Algorithm

The QSystemReadWriteLock class uses Linux kernel semaphores to synchronize access between readers and writers. Two semaphores ReadCount and WriteCount are used to allow either multiple concurrent readers or a single exclusive writer. When writers are waiting, any new readers must wait until all writers complete. That is, writers can starve readers.

The following semaphore conditions determine reader and writer operations.

OperationCondition Steps
Reader ProgressionWAIT(Increment ReadCount) AND WAIT(WriteCount == 0)
Reader CompleteWAIT(Decrement ReadCount)
Writer ProgressionWAIT(Increment WriteCount)
WAIT(ReadCount == 0)
Writer CompleteWAIT(Decrement WriteCount)

See also QSystemMutex.


Member Function Documentation

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

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

QSystemReadWriteLock::~QSystemReadWriteLock ()

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

unsigned int QSystemReadWriteLock::id () const

Return the id of lock as passed to the constructor.

bool QSystemReadWriteLock::isNull () const

Return true if the lock is invalid.

bool QSystemReadWriteLock::lockForRead ( int milliSec )

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

Aquisition of the read lock may fail if:

The timeout milliSec, in milliseconds, expired.

If the caller wants to poll the lock in a non-blocking way, it should specify a timeout of 0. If the caller would prefer to block until the lock 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 lock is acquired, regardless of the milliSec value.

The QSystemReadWriteLock instance does not refer to a valid lock.

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

bool QSystemReadWriteLock::lockForWrite ( int milliSec )

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

Aquisition of the write lock may fail if:

The timeout milliSec, in milliseconds, expired.

If the caller wants to poll the lock in a non-blocking way, it should specify a timeout of 0. If the caller would prefer to block until the lock 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 lock is acquired, regardless of the milliSec value.

The QSystemReadWriteLock instance does not refer to a valid lock.

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

void QSystemReadWriteLock::unlock ()

Release the lock.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3