Classes - Annotated - Tree - Functions - Home - Structure

QMutex Class Reference

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

#include <qthread.h>

Inherits Qt.

List of all member functions.

Public Members

QMutex ( bool recursive = FALSE )
virtual ~QMutex ()
void lock ()
void unlock ()
bool locked ()

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 (In Java terms, this is similar to the synchronized keyword). For example, say there is a method which prints a message to the user on two lines:

  void someMethod()
  {
     qDebug("Hello");
     qDebug("World");
  }

If this method is called simultaneously from two threads then the following sequence could result:

  Hello
  Hello
  World
  World

If we add a mutex:

  QMutex mutex;

  void someMethod()
  {
     mutex.lock();
     qDebug("Hello");
     qDebug("World");
     mutex.unlock();
  }

In Java terms this would be:

  void someMethod()
  {
     synchronized {
       qDebug("Hello");
       qDebug("World");
     }
  }

Then only one thread can execute someMethod at a time and the order of messages is always correct. This is a trivial example, of course, but applies to any other case where things need to happen in a particular sequence.

Member Function Documentation

QMutex::QMutex ( bool recursive = FALSE )

Constructs a new mutex. The mutex is created in an unlocked state. A recursive mutex is created if recursive is TRUE; a normal mutex is created if recursive is FALSE (default argument). With a recursive mutex, a thread can lock the same mutex multiple times and it will not be unlocked until a corresponding number of unlock() calls have been made.

QMutex::~QMutex () `[virtual]`

Destroys the mutex.

void QMutex::lock ()

Attempt to lock the mutex. If another thread has locked the mutex then this call will block until that thread has unlocked it.

bool QMutex::locked ()

Returns TRUE if the mutex is locked by another thread.

void QMutex::unlock ()

Unlocks the mutex. Attempting to unlock a mutex in a different thread to the one that locked it results in an error. Unlocking a mutex that is not locked results in undefined behaviour (varies between different Operating Systems' thread implementations).