CopperSpice API  1.7.2
QMutex Class Reference

The QMutex class provides access serialization between threads. More...

Inheritance diagram for QMutex:
QBasicMutex

Public Types

enum  RecursionMode
 

Public Methods

 QMutex (RecursionMode mode=NonRecursive)
 
 ~QMutex ()
 
- Public Methods inherited from QBasicMutex
bool isRecursive ()
 
void lock ()
 
bool tryLock (int timeout=0)
 
void unlock ()
 

Detailed Description

The QMutex class provides access serialization between threads.

The purpose of a QMutex is to protect an object, data structure or section of code so that only one thread can access it at a time (this is similar to the Java synchronized keyword). It is usually best to use a mutex with a QMutexLocker since this makes it easy to ensure that locking and unlocking are performed consistently.

For example, say there is a method that prints a message to the user on two lines:

int number = 6;
void method1()
{
number *= 5;
number /= 4;
}
void method2()
{
number *= 3;
number /= 2;
}

If these two methods are called in succession, the following happens:

// method1()
number *= 5; // number is now 30
number /= 4; // number is now 7
// method2()
number *= 3; // number is now 21
number /= 2; // number is now 10

If these two methods are called simultaneously from two threads then the following sequence could result:

// Thread 1 calls method1()
number *= 5; // number is now 30
// Thread 2 calls method2().
//
// Most likely Thread 1 has been put to sleep by the operating
// system to allow Thread 2 to run.
number *= 3; // number is now 90
number /= 2; // number is now 45
// Thread 1 finishes executing.
number /= 4; // number is now 11, instead of 10

If we add a mutex, we should get the result we want:

QMutex mutex;
int number = 6;
void method1()
{
mutex.lock();
number *= 5;
number /= 4;
mutex.unlock();
}
void method2()
{
mutex.lock();
number *= 3;
number /= 2;
mutex.unlock();
}

Then only one thread can modify number at any given time and the result is correct. This is a trivial example, of course, but applies to any other case where things need to happen in a particular sequence.

When you call lock() in a thread, other threads that try to call lock() in the same place will block until the thread that got the lock calls unlock(). A non-blocking alternative to lock() is tryLock().

See also
QMutexLocker, QReadWriteLock, QSemaphore, QWaitCondition

Member Enumeration Documentation

ConstantValueDescription
QMutex::Recursive1In this mode, a thread can lock the same mutex multiple times and the mutex will not be unlocked until a corresponding number of unlock() calls have been made.
QMutex::NonRecursive0In this mode, a thread may only lock a mutex once.
See also
QMutex()

Constructor & Destructor Documentation

QMutex::QMutex ( RecursionMode  mode = NonRecursive)
explicit

Constructs a new mutex. The mutex is created in an unlocked state.

If mode is QMutex::Recursive, a thread can lock the same mutex multiple times and the mutex will not be unlocked until a corresponding number of unlock() calls have been made. The default is QMutex::NonRecursive.

See also
lock(), unlock()
QMutex::~QMutex ( )

Destroys the mutex.

Warning
Destroying a locked mutex may result in undefined behavior.