CopperSpice API  1.7.2
QMutex Class Reference

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

Inheritance diagram for QMutex:

## 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:

number *= 5; // number is now 30
//
// 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
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().

## 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.
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.