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

See also unlock().

bool QMutex::locked ()

Returns TRUE if the mutex is locked by another thread and FALSE if not.

NOTE: Due to differing implementations of recursive mutexes on various platforms, calling this function from the same thread that previous locked the mutex will return undefined results.

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

See also lock().

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.