Thread Support in Qt

In version 2.2, Qt introduced thread support to Qt in the shape of some basic platform-independent threading classes, a thread-safe way of posting events and a global Qt library lock that allows you to call Qt methods from different threads.


This document is intended for an audience that has knowledge and experience with multithreaded applications. Recommended reading:

Enabling thread support

When Qt is installed on Windows, thread support is an option on some compilers. The mkfiles subdirectory contains build files for various compilers - the ones with -mt in the name have thread support enabled.

On Unix, thread support is enabled by adding the -thread option when running the configure script. On Unix platforms where multithreaded programs must be linked in special ways, such as with a special libc, installation will create a separate library, libqt-mt and hence threaded programs must be linked against this library (with -lqt-mt) rather than the regular Qt library.

On both platforms, you should compile with the macro QT_THREAD_SUPPORT defined (eg. compile with -DQT_THREAD_SUPPORT). On Windows, this is usually done by an entry in qconfig.h.

The Qt thread classes

The most important class, obviously, is QThread; this provides the means to start a new thread, which begins execution in your reimplementation of QThread::run(). This is similar to the Java thread class.

However, a thread class alone is not sufficient. In order to write threaded programs it is necessary to protect access to data that two threads wish to access at once. Therefore there is also a QMutex class; a thread can lock the mutex, and while it has it locked no other thread can lock the mutex; an attempt to do so will block the other thread until the mutex is released. For instance:

  class MyClass {
      void doStuff(int);

      QMutex mutex;
      int a;
      int b;

  // This sets a to c, and b to c*2

  void MyClass::doStuff(int c)

This ensures that only one thread at a time can be in MyClass::doStuff(), so b will always be equal to a*2.

Also necessary is a method for threads to wait for another thread to wake it up given a condition; the QWaitCondition class provides this. Threads wait for the QWaitCondition to indicate that something has happened, blocking until it does. When something happens, QWaitCondition can wake up all of the threads waiting for that event or one randomly selected thread (this is the same functionality as a POSIX Threads condition variable and is implemented as one on Unix). For instance:

  #include <qapplication.h>
  #include <qpushbutton.h>

  // global condition variable

  QWaitCondition mycond;

  // Worker class implementation

  class Worker : public QPushButton, public QThread
      Worker(QWidget *parent = 0, const char *name = 0)
        : QPushButton(parent, name)
          setText("Start Working");

          // connect the clicked() signal inherited from QPushButton to our
          // slotClicked() method
          connect(this, SIGNAL(clicked()), SLOT(slotClicked()));

          // call the start() method inherited from QThread... this starts
          // execution of the thread immediately

  public slots:
      void slotClicked()
          // wake up one thread waiting on this condition variable

      void run()
          // this method is called by the newly created thread...

          while(1) {
              // lock the application mutex, and set the caption of
              // the window to indicate that we are waiting to
              // start working

               // wait until we are told to continue

              // if we get here, we have been woken by another
              // thread... let's set the caption to indicate
              // that we are working

              // this could take a few seconds, minutes, hours, etc.
              // since it is in a separate thread from the GUI thread
              // the gui will not stop processing events...

  // main thread - all GUI events are handled by this thread.

  main(int argc, char **argv)
      QApplication app(argc, argv);

      // create a worker... the worker will run a thread when we do
      Worker firstworker(0, "worker");


      return app.exec();

This program will wake up the worker thread whenever you press the button; the thread will go off and do some work and then go back to waiting to be told to do some more work. If the worker thread is already working when the button is pressed, nothing will happen. When the thread finishes working and calls QWaitCondition::wait() again, then it can be started.

Thread-safe posting of events

In Qt, one thread is always the event thread - that is, the thread that pulls events from the window system and dispatches them to widgets. The static method QThread::postEvent posts events from threads other than the event thread. The event thread is woken up and the event delivered from within the event thread just as a normal window system event is. For instance, you could force a widget to repaint from a different thread by doing the following:

  QWidget *mywidget;
  QThread::postEvent( mywidget, new QPaintEvent( QRect(0, 0, 100, 100) ) );

This (asynchronously) makes mywidget to repaint a 100x100 square of its area.

The Qt library mutex

The Qt library mutex provides a method for calling Qt methods from threads other than the event thread. For instance:

  QApplication *qApp;
  QWidget *mywidget;



  QPainter p;


Calling a function in Qt without holding a mutex will generally result in unpredictable behavior. Calling a GUI-related function in Qt from a different thread requires holding the Qt library mutex. In this context, all functions that may ultimately access any graphics or window system resources are GUI-related. Using container classes, strings and I/O classes does not require any mutex if that object is only accessed by one thread.


Some things to watch out for when programming with threads:

Copyright © 2005 TrolltechTrademarks
Qt version 2.3.10