blob: 18b9e6725d89c710fa7e143754de1166c172b53d [file] [log] [blame]
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page thread-basics.html
\ingroup tutorials
\startpage {index.html}{Qt Reference Documentation}
\title Threading Basics
\brief An introduction to threads
\section1 What Are Threads?
Threads are about doing things in parallel, just like processes. So how do
threads differ from processes? While you are making calculations on a
spreadsheet, there may also be a media player running on the same desktop
playing your favorite song. Here is an example of two processes working in
parallel: one running the spreadsheet program; one running a media player.
Multitasking is a well known term for this. A closer look at the media
player reveals that there are again things going on in parallel within one
single process. While the media player is sending music to the audio driver,
the user interface with all its bells and whistles is being constantly
updated. This is what threads are for -- concurrency within one single
process.
So how is concurrency implemented? Parallel work on single core CPUs is an
illusion which is somewhat similar to the illusion of moving images in
cinema.
For processes, the illusion is produced by interrupting the processor's
work on one process after a very short time. Then the processor moves on to
the next process. In order to switch between processes, the current program
counter is saved and the next processor's program counter is loaded. This
is not sufficient because the same needs to be done with registers and
certain architecture and OS specific data.
Just as one CPU can power two or more processes, it is also possible to let
the CPU run on two different code segments of one single process. When a
process starts, it always executes one code segment and therefore the
process is said to have one thread. However, the program may decide to
start a second thread. Then, two different code sequences are processed
simultaneously inside one process. Concurrency is achieved on single core
CPUs by repeatedly saving program counters and registers then loading the
next thread's program counters and registers. No cooperation from the
program is required to cycle between the active threads. A thread may be in
any state when the switch to the next thread occurs.
The current trend in CPU design is to have several cores. A typical
single-threaded application can make use of only one core. However, a
program with multiple threads can be assigned to multiple cores, making
things happen in a truly concurrent way. As a result, distributing work
to more than one thread can make a program run much faster on multicore
CPUs because additional cores can be used.
\section2 GUI Thread and Worker Thread
As mentioned, each program has one thread when it is started. This thread
is called the "main thread" (also known as the "GUI thread" in Qt
applications). The Qt GUI must run in this thread. All widgets and several
related classes, for example QPixmap, don't work in secondary threads.
A secondary thread is commonly referred to as a "worker thread" because it
is used to offload processing work from the main thread.
\section2 Simultaneous Access to Data
Each thread has its own stack, which means each thread has its own call
history and local variables. Unlike processes, threads share the same
address space. The following diagram shows how the building blocks of
threads are located in memory. Program counter and registers of inactive
threads are typically kept in kernel space. There is a shared copy of the
code and a separate stack for each thread.
\image threadvisual-example.png "Thread visualization"
If two threads have a pointer to the same object, it is possible that both
threads will access that object at the same time and this can potentially
destroy the object's integrity. It's easy to imagine the many things that
can go wrong when two methods of the same object are executed
simultaneously.
Sometimes it is necessary to access one object from different threads;
for example, when objects living in different threads need to communicate.
Since threads use the same address space, it is easier and faster for
threads to exchange data than it is for processes. Data does not have to be
serialized and copied. Passing pointers is possible, but there must be a
strict coordination of what thread touches which object. Simultaneous
execution of operations on one object must be prevented. There are several
ways of achieving this and some of them are described below.
So what can be done safely? All objects created in a thread can be used
safely within that thread provided that other threads don't have references
to them and objects don't have implicit coupling with other threads. Such
implicit coupling may happen when data is shared between instances as with
static members, singletons or global data. Familiarize yourself with the
concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant}
classes and functions.
\section1 Using Threads
There are basically two use cases for threads:
\list
\li Make processing faster by making use of multicore processors.
\li Keep the GUI thread or other time critical threads responsive by
offloading long lasting processing or blocking calls to other threads.
\endlist
\section2 When to Use Alternatives to Threads
Developers need to be very careful with threads. It is easy to start other
threads, but very hard to ensure that all shared data remains consistent.
Problems are often hard to find because they may only show up once in a
while or only on specific hardware configurations. Before creating threads
to solve certain problems, possible alternatives should be considered.
\table
\header
\li Alternative
\li Comment
\row
\li QEventLoop::processEvents()
\li Calling QEventLoop::processEvents() repeatedly during a
time-consuming calculation prevents GUI blocking. However, this
solution doesn't scale well because the call to processEvents() may
occur too often, or not often enough, depending on hardware.
\row
\li QTimer
\li Background processing can sometimes be done conveniently using a
timer to schedule execution of a slot at some point in the future.
A timer with an interval of 0 will time out as soon as there are no
more events to process.
\row
\li QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
\li This is an alternative to having one or multiple threads, each with
a blocking read on a slow network connection. As long as the
calculation in response to a chunk of network data can be executed
quickly, this reactive design is better than synchronous waiting in
threads. Reactive design is less error prone and energy efficient
than threading. In many cases there are also performance benefits.
\endtable
In general, it is recommended to only use safe and tested paths and to
avoid introducing ad-hoc threading concepts. The QtConcurrent module provides an easy
interface for distributing work to all of the processor's cores. The
threading code is completely hidden in the QtConcurrent framework, so you
don't have to take care of the details. However, QtConcurrent can't be used
when communication with the running thread is needed, and it shouldn't be
used to handle blocking operations.
\section2 Which Qt Thread Technology Should You Use?
See the \l{Multithreading Technologies in Qt} page for an introduction to the
different approaches to multithreading to Qt, and for guidelines on how to
choose among them.
\section1 Qt Thread Basics
The following sections describe how QObjects interact with threads, how
programs can safely access data from multiple threads, and how asynchronous
execution produces results without blocking a thread.
\section2 QObject and Threads
As mentioned above, developers must always be careful when calling objects'
methods from other threads. \l{QObject#Thread Affinity}{Thread affinity}
does not change this situation.
Qt documentation marks several methods as thread-safe.
\l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe
method may be called from different threads simultaneously.
In cases where there is usually no concurrent access to methods, calling
non-thread-safe methods of objects in other threads may work thousands
of times before a concurrent access occurs, causing unexpected behavior.
Writing test code does not entirely ensure thread correctness, but it is
still important.
On Linux, Valgrind and Helgrind can help detect threading errors.
\section2 Protecting the Integrity of Data
When writing a multithread application, extra care must be taken to avoid
data corruption. See \l{Synchronizing Threads} for a discussion on how to
use threads safely.
\section2 Dealing with Asynchronous Execution
One way to obtain a worker thread's result is by waiting for the thread
to terminate. In many cases, however, a blocking wait isn't acceptable. The
alternative to a blocking wait are asynchronous result deliveries with
either posted events or queued signals and slots. This generates a certain
overhead because an operation's result does not appear on the next source
line, but in a slot located somewhere else in the source file. Qt
developers are used to working with this kind of asynchronous behavior
because it is much similar to the kind of event-driven programming used in
GUI applications.
\section1 Examples
Qt comes with several examples for using threads. See the class references
for QThread and QThreadPool for simple examples. See the \l{Threading and
Concurrent Programming Examples} page for more advanced ones.
\section1 Digging Deeper
Threading is a very complicated subject. Qt offers more classes for
threading than we have presented in this tutorial. The following materials
can help you go into the subject in more depth:
\list
\li The \l{Thread Support in Qt} document is a good starting point into
the reference documentation.
\li Qt comes with several additional examples for
\l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
\li Several good books describe how to work with Qt threads. The most
extensive coverage can be found in \e{Advanced Qt Programming} by Mark
Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and
QtConcurrent.
\endlist
*/