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

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-2001 Trolltech, all rights reserved.