|  | Home · Overviews · Examples |

# QMutex Class Reference
[com.trolltech.qt.core module]

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

## 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`, and `QWaitCondition`.