Doc: Discuss the concept of thread affinity in more detail
[qt:qt.git] / doc / src / tutorials / threads.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia.  For licensing terms and
14 ** conditions see http://qt.digia.com/licensing.  For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page thread-basics.html
30     \ingroup tutorials
31     \startpage {index.html}{Qt Reference Documentation}
32
33     \title Threading Basics
34     \brief An introduction to threads
35
36     \section1 What Are Threads?
37
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
48     process.
49
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
52     cinema.
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.
59
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.
70
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.
77
78     \section2 GUI Thread and Worker Thread
79
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.
86
87     \section2 Simultaneous Access to Data
88
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.
95
96     \image threadvisual-example.png "Thread visualization"
97
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
102     simultaneously.
103
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.
112
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.
120
121     \section1 Using Threads
122
123     There are basically two use cases for threads:
124
125     \list
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.
129     \endlist
130
131     \section2 When to Use Alternatives to Threads
132
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.
138
139     \table
140     \header
141         \o Alternative
142         \o Comment
143     \row
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.
149     \row
150         \o QTimer
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.
155     \row
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.
163     \endtable
164
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.
172
173     \section2 Which Qt Thread Technology Should You Use?
174
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
182     thread's lifetime.
183
184     \table
185     \header
186         \o Lifetime of thread
187         \o Development task
188         \o Solution
189     \row
190         \o One call
191         \o Run one method within another thread and quit the thread when the
192            method is finished.
193         \o Qt provides different solutions:
194            \list
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.
200            \endlist
201
202     \row
203         \o One call
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
211            remaining elements.
212     \row
213         \o One call
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
216            thread.
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
219            connections.
220
221     \row
222         \o Permanent
223         \o Have an object living in another thread and let it perform different
224            tasks upon request.
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.
229     \row
230         \o Permanent
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
233            the GUI thread.
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.
237     \endtable
238
239
240     \section1 Qt Thread Basics
241
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
245     exits.
246
247     \snippet examples/tutorials/threads/hellothread/hellothread.h 1
248
249     We derive a class from QThread and reimplement the \l{QThread::}{run()}
250     method.
251
252     \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1
253
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.
257
258     \snippet examples/tutorials/threads/hellothread/main.cpp 1
259
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.
269
270     This is the result of running the code:
271
272     \badcode
273     hello from GUI thread  3079423696
274     hello from worker thread  3076111216
275     \endcode
276
277
278     \section2 QObject and Threads
279
280     As mentioned above, developers must always be careful when calling objects'
281     methods from other threads. \l{QObject#Thread Affinity}{Thread affinity}
282     does not change this situation.
283     Qt documentation marks several methods as thread-safe.
284     \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe
285     method may be called from different threads simultaneously.
286
287     In cases where there is usually no concurrent access to methods, calling
288     non-thread-safe methods of objects in other threads may work thousands
289     of times before a concurrent access occurs, causing unexpected behavior.
290     Writing test code does not entirely ensure thread correctness, but it is
291     still important.
292     On Linux, Valgrind and Helgrind can help detect threading errors.
293
294     The anatomy of QThread is quite interesting:
295
296     \list
297     \o QThread does not live in the new thread where \l{QThread::}{run()} is
298        executed. It lives in the old thread.
299     \o Most QThread methods are the thread's control interface and are meant to
300        be called from the old thread. Do not move this interface to the newly
301        created thread using \l{QObject::}{moveToThread()}; i.e., calling
302        \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
303        practice.
304     \o \l{QThread::}{exec()} and the static methods
305        \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
306        \l{QThread::}{sleep()} are meant to be called from the newly created
307        thread.
308     \o Additional members defined in the QThread subclass are
309        accessible by both threads. The developer is responsible for
310        coordinating access. A typical strategy is to set the members before
311        \l{QThread::}{start()} is called. Once the worker thread is running,
312        the main thread should not touch the additional members anymore. After
313        the worker has terminated, the main thread can access the additional
314        members again. This is a convenient strategy for passing parameters to a
315        thread before it is started as well as for collecting the result once it
316        has terminated.
317     \endlist
318
319     \section2 Using a Mutex to Protect the Integrity of Data
320
321     A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
322     methods and remembers if it is already locked. A mutex is designed to be
323     called from multiple threads. \l{QMutex::}{lock()} returns immediately if
324     the mutex is not locked. The next call from another thread will find the
325     mutex in a locked state and then \l{QMutex::}{lock()} will block the thread
326     until the other thread calls \l{QMutex::}{unlock()}. This functionality can
327     make sure that a code section will be executed by only one thread at a time.
328
329     The following line sketches how a mutex can be used to make a method
330     thread-safe:
331
332     \code
333     void Worker::work()
334     {
335         this->mutex.lock();  // first thread can pass, other threads will be blocked here
336         doWork();
337         this->mutex.unlock();
338     }
339     \endcode
340
341     What happens if one thread does not unlock a mutex? The result can be a
342     frozen application. In the example above, an exception might be thrown and
343     \c{mutex.unlock()} will never be reached. To prevent problems like this,
344     QMutexLocker should be used.
345
346     \code
347     void Worker::work()
348     {
349         QMutexLocker locker(&mutex);  // Locks the mutex and unlocks when locker exits the scope
350         doWork();
351     }
352     \endcode
353
354     This looks easy, but mutexes introduce a new class of problems: deadlocks.
355     A deadlock happens when a thread waits for a mutex to become unlocked, but
356     the mutex remains locked because the owning thread is waiting for the first
357     thread to unlock it. The result is a frozen application. Mutexes can be
358     used to make a method thread safe. Most Qt methods aren't thread safe
359     because there is always a performance penalty when using mutexes.
360
361     It isn't always possible to lock and unlock a mutex in a method. Sometimes
362     the need to lock spans several calls. For example, modifying a container
363     with an iterator requires a sequence of several calls which should not be
364     interrupted by other threads. In such a scenario, locking can be achieved
365     with a mutex that is kept outside of the object to be manipulated. With an
366     external mutex, the duration of locking can be adjusted to the needs of the
367     operation. One disadvantage is that external mutexes aid locking, but do
368     not enforce it because users of the object may forget to use it.
369
370     \section2 Using the Event Loop to Prevent Data Corruption
371
372     The event loops of Qt are a very valuable tool for inter-thread
373     communication. Every thread may have its own event loop. A safe way of
374     calling a slot in another thread is by placing that call in another
375     thread's event loop. This ensures that the target object finishes the
376     method that is currently running before another method is started.
377
378     So how is it possible to put a method invocation in an event loop? Qt has
379     two ways of doing this. One way is via queued signal-slot connections; the
380     other way is to post an event with QCoreApplication::postEvent(). A queued
381     signal-slot connection is a signal slot connection that is executed
382     asynchronously. The internal implementation is based on posted events. The
383     arguments of the signal are put into the event loop and the signal method
384     returns immediately.
385
386     The connected slot will be executed at a time which depends on what else is
387     in the event loop.
388
389     Communication via the event loop eliminates the deadlock problem we face
390     when using mutexes. This is why we recommend using the event loop rather
391     than locking an object using a mutex.
392
393     \section2 Dealing with Asynchronous Execution
394
395     One way to obtain a worker thread's result is by waiting for the thread
396     to terminate. In many cases, however, a blocking wait isn't acceptable. The
397     alternative to a blocking wait are asynchronous result deliveries with
398     either posted events or queued signals and slots. This generates a certain
399     overhead because an operation's result does not appear on the next source
400     line, but in a slot located somewhere else in the source file. Qt
401     developers are used to working with this kind of asynchronous behavior
402     because it is much similar to the kind of event-driven programming used in
403     GUI applications.
404
405     \section1 Examples
406
407     This tutorial comes with examples for Qt's three basic ways of working with
408     threads. Two more examples show how to communicate with a running thread
409     and how a QObject can be placed in another thread, providing service to the
410     main thread.
411
412     \list
413     \o Using QThread as shown \l{Qt thread basics}{above}
414     \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool}
415     \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent}
416     \o \l{Example 3: Clock}{Communication with the GUI thread}
417     \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread
418        provides service to the main thread}
419     \endlist
420
421     The following examples can all be compiled and run independently. The source can
422     be found in the examples directory: examples/tutorials/threads/
423
424     \section2 Example 1: Using the Thread Pool
425
426     Creating and destroying threads frequently can be expensive. To avoid the
427     cost of thread creation, a thread pool can be used. A thread pool is a
428     place where threads can be parked and fetched. We can write the same
429     "hello thread" program as \l{Qt Thread Basics}{above} using the global
430     thread pool. We derive a class from QRunnable. The code we want to run in
431     another thread needs to be placed in the reimplemented QRunnable::run()
432     method.
433
434     \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp  1
435
436     We instantiate Work in main(), locate the global thread pool and use the
437     QThreadPool::start() method. Now the thread pool runs our worker in another
438     thread. Using the thread pool has a performance advantage because threads
439     are not destroyed after they have finished running. They are kept in a pool
440     and wait to be used again later.
441
442     \section2 Example 2: Using QtConcurrent
443
444     \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp  1
445
446     We write a global function hello() to implement the work. QtConcurrent::run()
447     is used to run the function in another thread. The result is a QFuture.
448     QFuture provides a method called \l{QFuture::}{waitForFinished()}, which
449     blocks until the calculation is completed. The real power of QtConcurrent
450     becomes visible when data can be made available in a container. QtConcurrent
451     provides several functions that are able to process itemized data on all
452     available cores simultaneously. The use of QtConcurrent is very similar to
453     applying an STL algorithm to an STL container.
454     \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and
455     clear example about how a container of images can be scaled on all available
456     cores. The image scaling example uses the blocking variants of the functions
457     used. For every blocking function there is also a non-blocking, asynchronous
458     counterpart. Getting results asynchronously is implemented with QFuture and
459     QFutureWatcher.
460
461     \section2 Example 3: Clock
462
463     \image thread_clock.png "clock"
464
465     We want to produce a clock application. The application has a GUI and a
466     worker thread. The worker thread checks every 10 milliseconds what time it
467     is. If the formatted time has changed, the result will be sent to the GUI
468     thread where it is displayed.
469
470     Of course, this is an overly complicated way of designing a clock and,
471     actually, a separate thread is unnecessary. We would be better off placing
472     the timer in the main thread because the calculation made in the timer slot
473     is very short-lived. This example is purely for instructional use and shows
474     how to communicate from a worker thread to a GUI thread. Note that
475     communication in this direction is easy. We only need to add a signal
476     to QThread and make a queued signal/slot connection to the main thread.
477     Communication from the GUI to the worker thread is shown in the next
478     example.
479
480     \snippet examples/tutorials/threads/clock/main.cpp  1
481
482     We've connected the \c clockThread with the label. The connection must be a
483     queued signal-slot connection because we want to put the call in the event
484     loop.
485
486     \snippet examples/tutorials/threads/clock/clockthread.h  1
487
488     We have derived a class from QThread and declared the \c sendTime() signal.
489
490     \snippet examples/tutorials/threads/clock/clockthread.cpp  1
491
492     The trickiest part of this example is that the timer is connected to its
493     slot via a direct connection. A default connection would produce a queued
494     signal-slot connection because the connected objects live in different
495     threads; remember that QThread does not live in the thread it creates.
496
497     Still it is safe to access ClockThread::timerHit() from the worker thread
498     because ClockThread::timerHit() is private and only touches local variables
499     and a private member that isn't touched by public methods.
500     QDateTime::currentDateTime() isn't marked as thread-safe in Qt
501     documentation, however we can get away with using it in this small
502     example because we know that the QDateTime::currentDateTime() static
503     method isn't used in any other threads.
504
505     \section2 Example 4: A Permanent Thread
506
507     This example shows how it is possible to have a QObject in a worker thread
508     that accepts requests from the GUI thread, does polling using a timer and
509     continuously reports results back to the GUI thread. The actual work
510     including the polling must be implemented in a class derived from QObject.
511     We have called this class \c WorkerObject in the code shown below. The
512     thread-specific code is hidden in a class called \c Thread, derived from
513     QThread.
514     \c Thread has two additional public members. The \c launchWorker() member
515     takes the worker object and moves it to another thread with a started event
516     loop.
517     The call blocks for a very short moment until the thread creation operation
518     is completed, allowing the worker object to be used again on the next line.
519     The \c Thread class's code is short but somewhat involved, so we only show
520     how to use the class.
521
522     \snippet examples/tutorials/threads/movedobject/main.cpp  1
523
524     QMetaObject::invokeMethod() calls a slot via the event loop. The worker
525     object's methods should not be called directly after the object has been
526     moved to another thread. We let the worker thread do some work and polling,
527     and use a timer to shut the application down after 3 seconds. Shutting the
528     worker down needs some care. We call \c{Thread::stop()} to exit the event
529     loop. We wait for the thread to terminate and, after this has occurred, we
530     delete the worker.
531
532     \section1 Digging Deeper
533
534     Threading is a very complicated subject. Qt offers more classes for
535     threading than we have presented in this tutorial. The following materials
536     can help you go into the subject in more depth:
537
538     \list
539     \o Good video tutorials about threads with Qt can be found in the material
540        from the \l{Training Day at Qt Developer Days 2009}.
541     \o The \l{Thread Support in Qt} document is a good starting point into
542        the reference documentation.
543     \o Qt comes with several additional examples for
544        \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
545     \o Several good books describe how to work with Qt threads. The most
546        extensive coverage can be found in \e{Advanced Qt Programming} by Mark
547        Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and
548        QtConcurrent.
549     \endlist
550 */