1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page thread-basics.html
31 \startpage {index.html}{Qt Reference Documentation}
33 \title Threading Basics
34 \brief An introduction to threads
36 \section1 What Are Threads?
38 Threads are about doing things in parallel, just like processes. So how do
39 threads differ from processes? While you are making calculations on a
40 spreadsheet, there may also be a media player running on the same desktop
41 playing your favorite song. Here is an example of two processes working in
42 parallel: one running the spreadsheet program; one running a media player.
43 Multitasking is a well known term for this. A closer look at the media
44 player reveals that there are again things going on in parallel within one
45 single process. While the media player is sending music to the audio driver,
46 the user interface with all its bells and whistles is being constantly
47 updated. This is what threads are for \mdash concurrency within one single
50 So how is concurrency implemented? Parallel work on single core CPUs is an
51 illusion which is somewhat similar to the illusion of moving images in
53 For processes, the illusion is produced by interrupting the processor's
54 work on one process after a very short time. Then the processor moves on to
55 the next process. In order to switch between processes, the current program
56 counter is saved and the next processor's program counter is loaded. This
57 is not sufficient because the same needs to be done with registers and
58 certain architecture and OS specific data.
60 Just as one CPU can power two or more processes, it is also possible to let
61 the CPU run on two different code segments of one single process. When a
62 process starts, it always executes one code segment and therefore the
63 process is said to have one thread. However, the program may decide to
64 start a second thread. Then, two different code sequences are processed
65 simultaneously inside one process. Concurrency is achieved on single core
66 CPUs by repeatedly saving program counters and registers then loading the
67 next thread's program counters and registers. No cooperation from the
68 program is required to cycle between the active threads. A thread may be in
69 any state when the switch to the next thread occurs.
71 The current trend in CPU design is to have several cores. A typical
72 single-threaded application can make use of only one core. However, a
73 program with multiple threads can be assigned to multiple cores, making
74 things happen in a truly concurrent way. As a result, distributing work
75 to more than one thread can make a program run much faster on multicore
76 CPUs because additional cores can be used.
78 \section2 GUI Thread and Worker Thread
80 As mentioned, each program has one thread when it is started. This thread
81 is called the "main thread" (also known as the "GUI thread" in Qt
82 applications). The Qt GUI must run in this thread. All widgets and several
83 related classes, for example QPixmap, don't work in secondary threads.
84 A secondary thread is commonly referred to as a "worker thread" because it
85 is used to offload processing work from the main thread.
87 \section2 Simultaneous Access to Data
89 Each thread has its own stack, which means each thread has its own call
90 history and local variables. Unlike processes, threads share the same
91 address space. The following diagram shows how the building blocks of
92 threads are located in memory. Program counter and registers of inactive
93 threads are typically kept in kernel space. There is a shared copy of the
94 code and a separate stack for each thread.
96 \image threadvisual-example.png "Thread visualization"
98 If two threads have a pointer to the same object, it is possible that both
99 threads will access that object at the same time and this can potentially
100 destroy the object's integrity. It's easy to imagine the many things that
101 can go wrong when two methods of the same object are executed
104 Sometimes it is necessary to access one object from different threads;
105 for example, when objects living in different threads need to communicate.
106 Since threads use the same address space, it is easier and faster for
107 threads to exchange data than it is for processes. Data does not have to be
108 serialized and copied. Passing pointers is possible, but there must be a
109 strict coordination of what thread touches which object. Simultaneous
110 execution of operations on one object must be prevented. There are several
111 ways of achieving this and some of them are described below.
113 So what can be done safely? All objects created in a thread can be used
114 safely within that thread provided that other threads don't have references
115 to them and objects don't have implicit coupling with other threads. Such
116 implicit coupling may happen when data is shared between instances as with
117 static members, singletons or global data. Familiarize yourself with the
118 concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant}
119 classes and functions.
121 \section1 Using Threads
123 There are basically two use cases for threads:
126 \o Make processing faster by making use of multicore processors.
127 \o Keep the GUI thread or other time critical threads responsive by
128 offloading long lasting processing or blocking calls to other threads.
131 \section2 When to Use Alternatives to Threads
133 Developers need to be very careful with threads. It is easy to start other
134 threads, but very hard to ensure that all shared data remains consistent.
135 Problems are often hard to find because they may only show up once in a
136 while or only on specific hardware configurations. Before creating threads
137 to solve certain problems, possible alternatives should be considered.
144 \o QEventLoop::processEvents()
145 \o Calling QEventLoop::processEvents() repeatedly during a
146 time-consuming calculation prevents GUI blocking. However, this
147 solution doesn't scale well because the call to processEvents() may
148 occur too often, or not often enough, depending on hardware.
151 \o Background processing can sometimes be done conveniently using a
152 timer to schedule execution of a slot at some point in the future.
153 A timer with an interval of 0 will time out as soon as there are no
154 more events to process.
156 \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
157 \o This is an alternative to having one or multiple threads, each with
158 a blocking read on a slow network connection. As long as the
159 calculation in response to a chunk of network data can be executed
160 quickly, this reactive design is better than synchronous waiting in
161 threads. Reactive design is less error prone and energy efficient
162 than threading. In many cases there are also performance benefits.
165 In general, it is recommended to only use safe and tested paths and to
166 avoid introducing ad-hoc threading concepts. QtConcurrent provides an easy
167 interface for distributing work to all of the processor's cores. The
168 threading code is completely hidden in the QtConcurrent framework, so you
169 don't have to take care of the details. However, QtConcurrent can't be used
170 when communication with the running thread is needed, and it shouldn't be
171 used to handle blocking operations.
173 \section2 Which Qt Thread Technology Should You Use?
175 Sometimes you want to do more than just running a method in the context of
176 another thread. You may want to have an object which lives in another
177 thread that provides a service to the GUI thread. Maybe you want another
178 thread to stay alive forever to poll hardware ports and send a signal to
179 the GUI thread when something noteworthy has happened. Qt provides
180 different solutions for developing threaded applications. The right
181 solution depends on the purpose of the new thread as well as on the
186 \o Lifetime of thread
191 \o Run one method within another thread and quit the thread when the
193 \o Qt provides different solutions:
195 \o Write a function and run it with QtConcurrent::run()
196 \o Derive a class from QRunnable and run it in the global thread
197 pool with QThreadPool::globalInstance()->start()
198 \o Derive a class from QThread, reimplement the QThread::run()
199 method and use QThread::start() to run it.
204 \o Operations are to be performed on all items of a container.
205 Processing should be performed using all available cores. A common
206 example is to produce thumbnails from a list of images.
207 \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for
208 applying operations on every container element,
209 \l{QtConcurrent::}{filter()} for selecting container elements, and
210 the option of specifying a reduce function for combining the
214 \o A long running operation has to be put in another thread. During the
215 course of processing, status information should be sent to the GUI
217 \o Use QThread, reimplement run and emit signals as needed. Connect the
218 signals to the GUI thread's slots using queued signal/slot
223 \o Have an object living in another thread and let it perform different
225 This means communication to and from the worker thread is required.
226 \o Derive a class from QObject and implement the necessary slots and
227 signals, move the object to a thread with a running event loop and
228 communicate with the object over queued signal/slot connections.
231 \o Have an object living in another thread, let the object perform
232 repeated tasks such as polling a port and enable communication with
234 \o Same as above but also use a timer in the worker thread to implement
235 polling. However, the best solution for polling is to avoid it
236 completely. Sometimes using QSocketNotifier is an alternative.
240 \section1 Qt Thread Basics
242 QThread is a very convenient cross platform abstraction of native platform
243 threads. Starting a thread is very simple. Let us look at a short piece of
244 code that generates another thread which says hello in that thread and then
247 \snippet examples/tutorials/threads/hellothread/hellothread.h 1
249 We derive a class from QThread and reimplement the \l{QThread::}{run()}
252 \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1
254 The run method contains the code that will be run in a separate thread. In
255 this example, a message containing the thread ID will be printed.
256 QThread::start() will call the method in another thread.
258 \snippet examples/tutorials/threads/hellothread/main.cpp 1
260 To start the thread, our thread object needs to be instantiated. The
261 \l{QThread::}{start()} method creates a new thread and calls the
262 reimplemented \l{QThread::}{run()} method in this new thread. Right after
263 \l{QThread::}{start()} is called, two program counters walk through the
264 program code. The main function starts with only the GUI thread running and
265 it should terminate with only the GUI thread running. Exiting the program
266 when another thread is still busy is a programming error, and therefore,
267 wait is called which blocks the calling thread until the
268 \l{QThread::}{run()} method has completed.
270 This is the result of running the code:
273 hello from GUI thread 3079423696
274 hello from worker thread 3076111216
278 \section2 QObject and Threads
280 A QObject is said to have a \e{thread affinity} or, in other words, that it
281 lives in a certain thread. This means that, at creation time, QObject saves
282 a pointer to the current thread. This information becomes relevant when an
283 event is posted with \l{QCoreApplication::}{postEvent()}. The event will be
284 put in the corresponding thread's event loop. If the thread where the
285 QObject lives doesn't have an event loop, the event will never be delivered.
287 To start an event loop, \l{QThread::}{exec()} must be called inside
288 \l{QThread::}{run()}. Thread affinity can be changed using
289 \l{QObject::}{moveToThread()}.
291 As mentioned above, developers must always be careful when calling objects'
292 methods from other threads. Thread affinity does not change this situation.
293 Qt documentation marks several methods as thread-safe.
294 \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe
295 method may be called from different threads simultaneously.
297 In cases where there is usually no concurrent access to methods, calling
298 non-thread-safe methods of objects in other threads may work thousands
299 of times before a concurrent access occurs, causing unexpected behavior.
300 Writing test code does not entirely ensure thread correctness, but it is
302 On Linux, Valgrind and Helgrind can help detect threading errors.
304 The anatomy of QThread is quite interesting:
307 \o QThread does not live in the new thread where \l{QThread::}{run()} is
308 executed. It lives in the old thread.
309 \o Most QThread methods are the thread's control interface and are meant to
310 be called from the old thread. Do not move this interface to the newly
311 created thread using \l{QObject::}{moveToThread()}; i.e., calling
312 \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
314 \o \l{QThread::}{exec()} and the static methods
315 \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
316 \l{QThread::}{sleep()} are meant to be called from the newly created
318 \o Additional members defined in the QThread subclass are
319 accessible by both threads. The developer is responsible for
320 coordinating access. A typical strategy is to set the members before
321 \l{QThread::}{start()} is called. Once the worker thread is running,
322 the main thread should not touch the additional members anymore. After
323 the worker has terminated, the main thread can access the additional
324 members again. This is a convenient strategy for passing parameters to a
325 thread before it is started as well as for collecting the result once it
329 A QObject's parent must always be in the same thread. This has a surprising
330 consequence for objects generated within the \l{QThread::}{run()} method:
333 void HelloThread::run()
335 QObject *object1 = new QObject(this); //error, parent must be in the same thread
336 QObject object2; // OK
337 QSharedPointer <QObject> object3(new QObject); // OK
341 \section2 Using a Mutex to Protect the Integrity of Data
343 A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
344 methods and remembers if it is already locked. A mutex is designed to be
345 called from multiple threads. \l{QMutex::}{lock()} returns immediately if
346 the mutex is not locked. The next call from another thread will find the
347 mutex in a locked state and then \l{QMutex::}{lock()} will block the thread
348 until the other thread calls \l{QMutex::}{unlock()}. This functionality can
349 make sure that a code section will be executed by only one thread at a time.
351 The following line sketches how a mutex can be used to make a method
357 this->mutex.lock(); // first thread can pass, other threads will be blocked here
359 this->mutex.unlock();
363 What happens if one thread does not unlock a mutex? The result can be a
364 frozen application. In the example above, an exception might be thrown and
365 \c{mutex.unlock()} will never be reached. To prevent problems like this,
366 QMutexLocker should be used.
371 QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope
376 This looks easy, but mutexes introduce a new class of problems: deadlocks.
377 A deadlock happens when a thread waits for a mutex to become unlocked, but
378 the mutex remains locked because the owning thread is waiting for the first
379 thread to unlock it. The result is a frozen application. Mutexes can be
380 used to make a method thread safe. Most Qt methods aren't thread safe
381 because there is always a performance penalty when using mutexes.
383 It isn't always possible to lock and unlock a mutex in a method. Sometimes
384 the need to lock spans several calls. For example, modifying a container
385 with an iterator requires a sequence of several calls which should not be
386 interrupted by other threads. In such a scenario, locking can be achieved
387 with a mutex that is kept outside of the object to be manipulated. With an
388 external mutex, the duration of locking can be adjusted to the needs of the
389 operation. One disadvantage is that external mutexes aid locking, but do
390 not enforce it because users of the object may forget to use it.
392 \section2 Using the Event Loop to Prevent Data Corruption
394 The event loops of Qt are a very valuable tool for inter-thread
395 communication. Every thread may have its own event loop. A safe way of
396 calling a slot in another thread is by placing that call in another
397 thread's event loop. This ensures that the target object finishes the
398 method that is currently running before another method is started.
400 So how is it possible to put a method invocation in an event loop? Qt has
401 two ways of doing this. One way is via queued signal-slot connections; the
402 other way is to post an event with QCoreApplication::postEvent(). A queued
403 signal-slot connection is a signal slot connection that is executed
404 asynchronously. The internal implementation is based on posted events. The
405 arguments of the signal are put into the event loop and the signal method
408 The connected slot will be executed at a time which depends on what else is
411 Communication via the event loop eliminates the deadlock problem we face
412 when using mutexes. This is why we recommend using the event loop rather
413 than locking an object using a mutex.
415 \section2 Dealing with Asynchronous Execution
417 One way to obtain a worker thread's result is by waiting for the thread
418 to terminate. In many cases, however, a blocking wait isn't acceptable. The
419 alternative to a blocking wait are asynchronous result deliveries with
420 either posted events or queued signals and slots. This generates a certain
421 overhead because an operation's result does not appear on the next source
422 line, but in a slot located somewhere else in the source file. Qt
423 developers are used to working with this kind of asynchronous behavior
424 because it is much similar to the kind of event-driven programming used in
429 This tutorial comes with examples for Qt's three basic ways of working with
430 threads. Two more examples show how to communicate with a running thread
431 and how a QObject can be placed in another thread, providing service to the
435 \o Using QThread as shown \l{Qt thread basics}{above}
436 \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool}
437 \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent}
438 \o \l{Example 3: Clock}{Communication with the GUI thread}
439 \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread
440 provides service to the main thread}
443 The following examples can all be compiled and run independently. The source can
444 be found in the examples directory: examples/tutorials/threads/
446 \section2 Example 1: Using the Thread Pool
448 Creating and destroying threads frequently can be expensive. To avoid the
449 cost of thread creation, a thread pool can be used. A thread pool is a
450 place where threads can be parked and fetched. We can write the same
451 "hello thread" program as \l{Qt Thread Basics}{above} using the global
452 thread pool. We derive a class from QRunnable. The code we want to run in
453 another thread needs to be placed in the reimplemented QRunnable::run()
456 \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1
458 We instantiate Work in main(), locate the global thread pool and use the
459 QThreadPool::start() method. Now the thread pool runs our worker in another
460 thread. Using the thread pool has a performance advantage because threads
461 are not destroyed after they have finished running. They are kept in a pool
462 and wait to be used again later.
464 \section2 Example 2: Using QtConcurrent
466 \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1
468 We write a global function hello() to implement the work. QtConcurrent::run()
469 is used to run the function in another thread. The result is a QFuture.
470 QFuture provides a method called \l{QFuture::}{waitForFinished()}, which
471 blocks until the calculation is completed. The real power of QtConcurrent
472 becomes visible when data can be made available in a container. QtConcurrent
473 provides several functions that are able to process itemized data on all
474 available cores simultaneously. The use of QtConcurrent is very similar to
475 applying an STL algorithm to an STL container.
476 \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and
477 clear example about how a container of images can be scaled on all available
478 cores. The image scaling example uses the blocking variants of the functions
479 used. For every blocking function there is also a non-blocking, asynchronous
480 counterpart. Getting results asynchronously is implemented with QFuture and
483 \section2 Example 3: Clock
485 \image thread_clock.png "clock"
487 We want to produce a clock application. The application has a GUI and a
488 worker thread. The worker thread checks every 10 milliseconds what time it
489 is. If the formatted time has changed, the result will be sent to the GUI
490 thread where it is displayed.
492 Of course, this is an overly complicated way of designing a clock and,
493 actually, a separate thread is unnecessary. We would be better off placing
494 the timer in the main thread because the calculation made in the timer slot
495 is very short-lived. This example is purely for instructional use and shows
496 how to communicate from a worker thread to a GUI thread. Note that
497 communication in this direction is easy. We only need to add a signal
498 to QThread and make a queued signal/slot connection to the main thread.
499 Communication from the GUI to the worker thread is shown in the next
502 \snippet examples/tutorials/threads/clock/main.cpp 1
504 We've connected the \c clockThread with the label. The connection must be a
505 queued signal-slot connection because we want to put the call in the event
508 \snippet examples/tutorials/threads/clock/clockthread.h 1
510 We have derived a class from QThread and declared the \c sendTime() signal.
512 \snippet examples/tutorials/threads/clock/clockthread.cpp 1
514 The trickiest part of this example is that the timer is connected to its
515 slot via a direct connection. A default connection would produce a queued
516 signal-slot connection because the connected objects live in different
517 threads; remember that QThread does not live in the thread it creates.
519 Still it is safe to access ClockThread::timerHit() from the worker thread
520 because ClockThread::timerHit() is private and only touches local variables
521 and a private member that isn't touched by public methods.
522 QDateTime::currentDateTime() isn't marked as thread-safe in Qt
523 documentation, however we can get away with using it in this small
524 example because we know that the QDateTime::currentDateTime() static
525 method isn't used in any other threads.
527 \section2 Example 4: A Permanent Thread
529 This example shows how it is possible to have a QObject in a worker thread
530 that accepts requests from the GUI thread, does polling using a timer and
531 continuously reports results back to the GUI thread. The actual work
532 including the polling must be implemented in a class derived from QObject.
533 We have called this class \c WorkerObject in the code shown below. The
534 thread-specific code is hidden in a class called \c Thread, derived from
536 \c Thread has two additional public members. The \c launchWorker() member
537 takes the worker object and moves it to another thread with a started event
539 The call blocks for a very short moment until the thread creation operation
540 is completed, allowing the worker object to be used again on the next line.
541 The \c Thread class's code is short but somewhat involved, so we only show
542 how to use the class.
544 \snippet examples/tutorials/threads/movedobject/main.cpp 1
546 QMetaObject::invokeMethod() calls a slot via the event loop. The worker
547 object's methods should not be called directly after the object has been
548 moved to another thread. We let the worker thread do some work and polling,
549 and use a timer to shut the application down after 3 seconds. Shutting the
550 worker down needs some care. We call \c{Thread::stop()} to exit the event
551 loop. We wait for the thread to terminate and, after this has occurred, we
554 \section1 Digging Deeper
556 Threading is a very complicated subject. Qt offers more classes for
557 threading than we have presented in this tutorial. The following materials
558 can help you go into the subject in more depth:
561 \o Good video tutorials about threads with Qt can be found in the material
562 from the \l{Training Day at Qt Developer Days 2009}.
563 \o The \l{Thread Support in Qt} document is a good starting point into
564 the reference documentation.
565 \o Qt comes with several additional examples for
566 \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
567 \o Several good books describe how to work with Qt threads. The most
568 extensive coverage can be found in \e{Advanced Qt Programming} by Mark
569 Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and