--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $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 \mdash 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
+ \o Make processing faster by making use of multicore processors.
+ \o 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
+ \o Alternative
+ \o Comment
+ \row
+ \o QEventLoop::processEvents()
+ \o 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
+ \o QTimer
+ \o 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
+ \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
+ \o 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. QtConcurrent 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?
+
+ Sometimes you want to do more than just running a method in the context of
+ another thread. You may want to have an object which lives in another
+ thread that provides a service to the GUI thread. Maybe you want another
+ thread to stay alive forever to poll hardware ports and send a signal to
+ the GUI thread when something noteworthy has happened. Qt provides
+ different solutions for developing threaded applications. The right
+ solution depends on the purpose of the new thread as well as on the
+ thread's lifetime.
+
+ \table
+ \header
+ \o Lifetime of thread
+ \o Development task
+ \o Solution
+ \row
+ \o One call
+ \o Run one method within another thread and quit the thread when the
+ method is finished.
+ \o Qt provides different solutions:
+ \list
+ \o Write a function and run it with QtConcurrent::run()
+ \o Derive a class from QRunnable and run it in the global thread
+ pool with QThreadPool::globalInstance()->start()
+ \o Derive a class from QThread, reimplement the QThread::run()
+ method and use QThread::start() to run it.
+ \endlist
+
+ \row
+ \o One call
+ \o Operations are to be performed on all items of a container.
+ Processing should be performed using all available cores. A common
+ example is to produce thumbnails from a list of images.
+ \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for
+ applying operations on every container element,
+ \l{QtConcurrent::}{filter()} for selecting container elements, and
+ the option of specifying a reduce function for combining the
+ remaining elements.
+ \row
+ \o One call
+ \o A long running operation has to be put in another thread. During the
+ course of processing, status information should be sent to the GUI
+ thread.
+ \o Use QThread, reimplement run and emit signals as needed. Connect the
+ signals to the GUI thread's slots using queued signal/slot
+ connections.
+
+ \row
+ \o Permanent
+ \o Have an object living in another thread and let it perform different
+ tasks upon request.
+ This means communication to and from the worker thread is required.
+ \o Derive a class from QObject and implement the necessary slots and
+ signals, move the object to a thread with a running event loop and
+ communicate with the object over queued signal/slot connections.
+ \row
+ \o Permanent
+ \o Have an object living in another thread, let the object perform
+ repeated tasks such as polling a port and enable communication with
+ the GUI thread.
+ \o Same as above but also use a timer in the worker thread to implement
+ polling. However, the best solution for polling is to avoid it
+ completely. Sometimes using QSocketNotifier is an alternative.
+ \endtable
+
+
+ \section1 Qt Thread Basics
+
+ QThread is a very convenient cross platform abstraction of native platform
+ threads. Starting a thread is very simple. Let us look at a short piece of
+ code that generates another thread which says hello in that thread and then
+ exits.
+
+ \snippet examples/tutorials/threads/hellothread/hellothread.h 1
+
+ We derive a class from QThread and reimplement the \l{QThread::}{run()}
+ method.
+
+ \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1
+
+ The run method contains the code that will be run in a separate thread. In
+ this example, a message containing the thread ID will be printed.
+ QThread::start() will call the method in another thread.
+
+ \snippet examples/tutorials/threads/hellothread/main.cpp 1
+
+ To start the thread, our thread object needs to be instantiated. The
+ \l{QThread::}{start()} method creates a new thread and calls the
+ reimplemented \l{QThread::}{run()} method in this new thread. Right after
+ \l{QThread::}{start()} is called, two program counters walk through the
+ program code. The main function starts with only the GUI thread running and
+ it should terminate with only the GUI thread running. Exiting the program
+ when another thread is still busy is a programming error, and therefore,
+ wait is called which blocks the calling thread until the
+ \l{QThread::}{run()} method has completed.
+
+ This is the result of running the code:
+
+ \badcode
+ hello from GUI thread 3079423696
+ hello from worker thread 3076111216
+ \endcode
+
+
+ \section2 QObject and Threads
+
+ A QObject is said to have a \e{thread affinity} or, in other words, that it
+ lives in a certain thread. This means that, at creation time, QObject saves
+ a pointer to the current thread. This information becomes relevant when an
+ event is posted with \l{QCoreApplication::}{postEvent()}. The event will be
+ put in the corresponding thread's event loop. If the thread where the
+ QObject lives doesn't have an event loop, the event will never be delivered.
+
+ To start an event loop, \l{QThread::}{exec()} must be called inside
+ \l{QThread::}{run()}. Thread affinity can be changed using
+ \l{QObject::}{moveToThread()}.
+
+ As mentioned above, developers must always be careful when calling objects'
+ methods from other threads. 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.
+
+ The anatomy of QThread is quite interesting:
+
+ \list
+ \o QThread does not live in the new thread where \l{QThread::}{run()} is
+ executed. It lives in the old thread.
+ \o Most QThread methods are the thread's control interface and are meant to
+ be called from the old thread. Do not move this interface to the newly
+ created thread using \l{QObject::}{moveToThread()}; i.e., calling
+ \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
+ practice.
+ \o \l{QThread::}{exec()} and the static methods
+ \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
+ \l{QThread::}{sleep()} are meant to be called from the newly created
+ thread.
+ \o Additional members defined in the QThread subclass are
+ accessible by both threads. The developer is responsible for
+ coordinating access. A typical strategy is to set the members before
+ \l{QThread::}{start()} is called. Once the worker thread is running,
+ the main thread should not touch the additional members anymore. After
+ the worker has terminated, the main thread can access the additional
+ members again. This is a convenient strategy for passing parameters to a
+ thread before it is started as well as for collecting the result once it
+ has terminated.
+ \endlist
+
+ A QObject's parent must always be in the same thread. This has a surprising
+ consequence for objects generated within the \l{QThread::}{run()} method:
+
+ \code
+ void HelloThread::run()
+ {
+ QObject *object1 = new QObject(this); //error, parent must be in the same thread
+ QObject object2; // OK
+ QSharedPointer <QObject> object3(new QObject); // OK
+ }
+ \endcode
+
+ \section2 Using a Mutex to Protect the Integrity of Data
+
+ A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
+ methods and remembers if it is already locked. A mutex is designed to be
+ called from multiple threads. \l{QMutex::}{lock()} returns immediately if
+ the mutex is not locked. The next call from another thread will find the
+ mutex in a locked state and then \l{QMutex::}{lock()} will block the thread
+ until the other thread calls \l{QMutex::}{unlock()}. This functionality can
+ make sure that a code section will be executed by only one thread at a time.
+
+ The following line sketches how a mutex can be used to make a method
+ thread-safe:
+
+ \code
+ void Worker::work()
+ {
+ this->mutex.lock(); // first thread can pass, other threads will be blocked here
+ doWork();
+ this->mutex.unlock();
+ }
+ \endcode
+
+ What happens if one thread does not unlock a mutex? The result can be a
+ frozen application. In the example above, an exception might be thrown and
+ \c{mutex.unlock()} will never be reached. To prevent problems like this,
+ QMutexLocker should be used.
+
+ \code
+ void Worker::work()
+ {
+ QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope
+ doWork();
+ }
+ \endcode
+
+ This looks easy, but mutexes introduce a new class of problems: deadlocks.
+ A deadlock happens when a thread waits for a mutex to become unlocked, but
+ the mutex remains locked because the owning thread is waiting for the first
+ thread to unlock it. The result is a frozen application. Mutexes can be
+ used to make a method thread safe. Most Qt methods aren't thread safe
+ because there is always a performance penalty when using mutexes.
+
+ It isn't always possible to lock and unlock a mutex in a method. Sometimes
+ the need to lock spans several calls. For example, modifying a container
+ with an iterator requires a sequence of several calls which should not be
+ interrupted by other threads. In such a scenario, locking can be achieved
+ with a mutex that is kept outside of the object to be manipulated. With an
+ external mutex, the duration of locking can be adjusted to the needs of the
+ operation. One disadvantage is that external mutexes aid locking, but do
+ not enforce it because users of the object may forget to use it.
+
+ \section2 Using the Event Loop to Prevent Data Corruption
+
+ The event loops of Qt are a very valuable tool for inter-thread
+ communication. Every thread may have its own event loop. A safe way of
+ calling a slot in another thread is by placing that call in another
+ thread's event loop. This ensures that the target object finishes the
+ method that is currently running before another method is started.
+
+ So how is it possible to put a method invocation in an event loop? Qt has
+ two ways of doing this. One way is via queued signal-slot connections; the
+ other way is to post an event with QCoreApplication::postEvent(). A queued
+ signal-slot connection is a signal slot connection that is executed
+ asynchronously. The internal implementation is based on posted events. The
+ arguments of the signal are put into the event loop and the signal method
+ returns immediately.
+
+ The connected slot will be executed at a time which depends on what else is
+ in the event loop.
+
+ Communication via the event loop eliminates the deadlock problem we face
+ when using mutexes. This is why we recommend using the event loop rather
+ than locking an object using a mutex.
+
+ \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
+
+ This tutorial comes with examples for Qt's three basic ways of working with
+ threads. Two more examples show how to communicate with a running thread
+ and how a QObject can be placed in another thread, providing service to the
+ main thread.
+
+ \list
+ \o Using QThread as shown \l{Qt thread basics}{above}
+ \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool}
+ \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent}
+ \o \l{Example 3: Clock}{Communication with the GUI thread}
+ \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread
+ provides service to the main thread}
+ \endlist
+
+ The following examples can all be compiled and run independently. The source can
+ be found in the examples directory: examples/tutorials/threads/
+
+ \section2 Example 1: Using the Thread Pool
+
+ Creating and destroying threads frequently can be expensive. To avoid the
+ cost of thread creation, a thread pool can be used. A thread pool is a
+ place where threads can be parked and fetched. We can write the same
+ "hello thread" program as \l{Qt Thread Basics}{above} using the global
+ thread pool. We derive a class from QRunnable. The code we want to run in
+ another thread needs to be placed in the reimplemented QRunnable::run()
+ method.
+
+ \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1
+
+ We instantiate Work in main(), locate the global thread pool and use the
+ QThreadPool::start() method. Now the thread pool runs our worker in another
+ thread. Using the thread pool has a performance advantage because threads
+ are not destroyed after they have finished running. They are kept in a pool
+ and wait to be used again later.
+
+ \section2 Example 2: Using QtConcurrent
+
+ \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1
+
+ We write a global function hello() to implement the work. QtConcurrent::run()
+ is used to run the function in another thread. The result is a QFuture.
+ QFuture provides a method called \l{QFuture::}{waitForFinished()}, which
+ blocks until the calculation is completed. The real power of QtConcurrent
+ becomes visible when data can be made available in a container. QtConcurrent
+ provides several functions that are able to process itemized data on all
+ available cores simultaneously. The use of QtConcurrent is very similar to
+ applying an STL algorithm to an STL container.
+ \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and
+ clear example about how a container of images can be scaled on all available
+ cores. The image scaling example uses the blocking variants of the functions
+ used. For every blocking function there is also a non-blocking, asynchronous
+ counterpart. Getting results asynchronously is implemented with QFuture and
+ QFutureWatcher.
+
+ \section2 Example 3: Clock
+
+ \image thread_clock.png "clock"
+
+ We want to produce a clock application. The application has a GUI and a
+ worker thread. The worker thread checks every 10 milliseconds what time it
+ is. If the formatted time has changed, the result will be sent to the GUI
+ thread where it is displayed.
+
+ Of course, this is an overly complicated way of designing a clock and,
+ actually, a separate thread is unnecessary. We would be better off placing
+ the timer in the main thread because the calculation made in the timer slot
+ is very short-lived. This example is purely for instructional use and shows
+ how to communicate from a worker thread to a GUI thread. Note that
+ communication in this direction is easy. We only need to add a signal
+ to QThread and make a queued signal/slot connection to the main thread.
+ Communication from the GUI to the worker thread is shown in the next
+ example.
+
+ \snippet examples/tutorials/threads/clock/main.cpp 1
+
+ We've connected the \c clockThread with the label. The connection must be a
+ queued signal-slot connection because we want to put the call in the event
+ loop.
+
+ \snippet examples/tutorials/threads/clock/clockthread.h 1
+
+ We have derived a class from QThread and declared the \c sendTime() signal.
+
+ \snippet examples/tutorials/threads/clock/clockthread.cpp 1
+
+ The trickiest part of this example is that the timer is connected to its
+ slot via a direct connection. A default connection would produce a queued
+ signal-slot connection because the connected objects live in different
+ threads; remember that QThread does not live in the thread it creates.
+
+ Still it is safe to access ClockThread::timerHit() from the worker thread
+ because ClockThread::timerHit() is private and only touches local variables
+ and a private member that isn't touched by public methods.
+ QDateTime::currentDateTime() isn't marked as thread-safe in Qt
+ documentation, however we can get away with using it in this small
+ example because we know that the QDateTime::currentDateTime() static
+ method isn't used in any other threads.
+
+ \section2 Example 4: A Permanent Thread
+
+ This example shows how it is possible to have a QObject in a worker thread
+ that accepts requests from the GUI thread, does polling using a timer and
+ continuously reports results back to the GUI thread. The actual work
+ including the polling must be implemented in a class derived from QObject.
+ We have called this class \c WorkerObject in the code shown below. The
+ thread-specific code is hidden in a class called \c Thread, derived from
+ QThread.
+ \c Thread has two additional public members. The \c launchWorker() member
+ takes the worker object and moves it to another thread with a started event
+ loop.
+ The call blocks for a very short moment until the thread creation operation
+ is completed, allowing the worker object to be used again on the next line.
+ The \c Thread class's code is short but somewhat involved, so we only show
+ how to use the class.
+
+ \snippet examples/tutorials/threads/movedobject/main.cpp 1
+
+ QMetaObject::invokeMethod() calls a slot via the event loop. The worker
+ object's methods should not be called directly after the object has been
+ moved to another thread. We let the worker thread do some work and polling,
+ and use a timer to shut the application down after 3 seconds. Shutting the
+ worker down needs some care. We call \c{Thread::stop()} to exit the event
+ loop. We wait for the thread to terminate and, after this has occurred, we
+ delete the worker.
+
+ \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
+ \o Good video tutorials about threads with Qt can be found in the material
+ from the \l{Training Day at Qt Developer Days 2009}.
+ \o The \l{Thread Support in Qt} document is a good starting point into
+ the reference documentation.
+ \o Qt comes with several additional examples for
+ \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
+ \o 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
+*/
****************************************************************************/
/*!
- \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 \mdash 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:
+ \group thread
+ \title Threading Classes
+*/
- \list
- \o Make processing faster by making use of multicore processors.
- \o Keep the GUI thread or other time critical threads responsive by
- offloading long lasting processing or blocking calls to other threads.
- \endlist
+/*!
+ \page threads.html
+ \title Thread Support in Qt
+ \ingroup qt-basic-concepts
+ \brief A detailed discussion of thread handling in Qt.
- \section2 When to Use Alternatives to Threads
+ \ingroup frameworks-technologies
- 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.
+ \nextpage Starting Threads with QThread
- \table
- \header
- \o Alternative
- \o Comment
- \row
- \o QEventLoop::processEvents()
- \o 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
- \o QTimer
- \o 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
- \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
- \o 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
+ Qt provides thread support in the form of platform-independent
+ threading classes, a thread-safe way of posting events, and
+ signal-slot connections across threads. This makes it easy to
+ develop portable multithreaded Qt applications and take advantage
+ of multiprocessor machines. Multithreaded programming is also a
+ useful paradigm for performing time-consuming operations without
+ freezing the user interface of an application.
- In general, it is recommended to only use safe and tested paths and to
- avoid introducing ad-hoc threading concepts. QtConcurrent 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?
-
- Sometimes you want to do more than just running a method in the context of
- another thread. You may want to have an object which lives in another
- thread that provides a service to the GUI thread. Maybe you want another
- thread to stay alive forever to poll hardware ports and send a signal to
- the GUI thread when something noteworthy has happened. Qt provides
- different solutions for developing threaded applications. The right
- solution depends on the purpose of the new thread as well as on the
- thread's lifetime.
+ Earlier versions of Qt offered an option to build the library
+ without thread support. Since Qt 4.0, threads are always enabled.
- \table
- \header
- \o Lifetime of thread
- \o Development task
- \o Solution
- \row
- \o One call
- \o Run one method within another thread and quit the thread when the
- method is finished.
- \o Qt provides different solutions:
- \list
- \o Write a function and run it with QtConcurrent::run()
- \o Derive a class from QRunnable and run it in the global thread
- pool with QThreadPool::globalInstance()->start()
- \o Derive a class from QThread, reimplement the QThread::run()
- method and use QThread::start() to run it.
- \endlist
+ \section1 Topics:
- \row
- \o One call
- \o Operations are to be performed on all items of a container.
- Processing should be performed using all available cores. A common
- example is to produce thumbnails from a list of images.
- \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for
- applying operations on every container element,
- \l{QtConcurrent::}{filter()} for selecting container elements, and
- the option of specifying a reduce function for combining the
- remaining elements.
- \row
- \o One call
- \o A long running operation has to be put in another thread. During the
- course of processing, status information should be sent to the GUI
- thread.
- \o Use QThread, reimplement run and emit signals as needed. Connect the
- signals to the GUI thread's slots using queued signal/slot
- connections.
+ \list
+ \o \l{Recommended Reading}
+ \o \l{The Threading Classes}
+ \o \l{Starting Threads with QThread}
+ \o \l{Synchronizing Threads}
+ \o \l{Reentrancy and Thread-Safety}
+ \o \l{Threads and QObjects}
+ \o \l{Concurrent Programming}
+ \o \l{Thread-Support in Qt Modules}
+ \endlist
- \row
- \o Permanent
- \o Have an object living in another thread and let it perform different
- tasks upon request.
- This means communication to and from the worker thread is required.
- \o Derive a class from QObject and implement the necessary slots and
- signals, move the object to a thread with a running event loop and
- communicate with the object over queued signal/slot connections.
- \row
- \o Permanent
- \o Have an object living in another thread, let the object perform
- repeated tasks such as polling a port and enable communication with
- the GUI thread.
- \o Same as above but also use a timer in the worker thread to implement
- polling. However, the best solution for polling is to avoid it
- completely. Sometimes using QSocketNotifier is an alternative.
- \endtable
+ \section1 Recommended Reading
+ This document is intended for an audience that has knowledge of,
+ and experience with, multithreaded applications. If you are new
+ to threading see our Recommended Reading list:
- \section1 Qt Thread Basics
+ \list
+ \o \l{Threads Primer: A Guide to Multithreaded Programming}
+ \o \l{Thread Time: The Multithreaded Programming Guide}
+ \o \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing}
+ \o \l{Win32 Multithreaded Programming}
+ \endlist
- QThread is a very convenient cross platform abstraction of native platform
- threads. Starting a thread is very simple. Let us look at a short piece of
- code that generates another thread which says hello in that thread and then
- exits.
+ \section1 The Threading Classes
- \snippet examples/tutorials/threads/hellothread/hellothread.h 1
+ These classes are relevant to threaded applications.
- We derive a class from QThread and reimplement the \l{QThread::}{run()}
- method.
+ \annotatedlist thread
- \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1
+\omit
+ \list
+ \o QThread provides the means to start a new thread.
+ \o QThreadStorage provides per-thread data storage.
+ \o QThreadPool manages a pool of threads that run QRunnable objects.
+ \o QRunnable is an abstract class representing a runnable object.
+ \o QMutex provides a mutual exclusion lock, or mutex.
+ \o QMutexLocker is a convenience class that automatically locks
+ and unlocks a QMutex.
+ \o QReadWriteLock provides a lock that allows simultaneous read access.
+ \o QReadLocker and QWriteLocker are convenience classes that automatically
+ lock and unlock a QReadWriteLock.
+ \o QSemaphore provides an integer semaphore (a generalization of a mutex).
+ \o QWaitCondition provides a way for threads to go to sleep until
+ woken up by another thread.
+ \o QAtomicInt provides atomic operations on integers.
+ \o QAtomicPointer provides atomic operations on pointers.
+ \endlist
+\endomit
- The run method contains the code that will be run in a separate thread. In
- this example, a message containing the thread ID will be printed.
- QThread::start() will call the method in another thread.
+ \note Qt's threading classes are implemented with native threading APIs;
+ e.g., Win32 and pthreads. Therefore, they can be used with threads of the
+ same native API.
+*/
- \snippet examples/tutorials/threads/hellothread/main.cpp 1
+/*!
+ \page threads-starting.html
+ \title Starting Threads with QThread
+
+ \contentspage Thread Support in Qt
+ \nextpage Synchronizing Threads
+
+ A QThread instance represents a thread and provides the means to
+ \l{QThread::start()}{start()} a thread, which will then execute the
+ reimplementation of QThread::run(). The \c run() implementation is for a
+ thread what the \c main() entry point is for the application. All code
+ executed in a call stack that starts in the \c run() function is executed
+ by the new thread, and the thread finishes when the function returns.
+ QThread emits signals to indicate that the thread started or finished
+ executing.
+
+ \section1 Creating a Thread
+
+ To create a thread, subclass QThread and reimplement its
+ \l{QThread::run()}{run()} function. For example:
+
+ \snippet doc/src/snippets/threads/threads.h 0
+ \codeline
+ \snippet doc/src/snippets/threads/threads.cpp 0
+ \snippet doc/src/snippets/threads/threads.cpp 1
+ \dots
+ \snippet doc/src/snippets/threads/threads.cpp 2
+
+ \section1 Starting a Thread
+
+ Then, create an instance of the thread object and call
+ QThread::start(). Note that you must create the QApplication (or
+ QCoreApplication) object before you can create a QThread.
+
+ The function will return immediately and the
+ main thread will continue. The code that appears in the
+ \l{QThread::run()}{run()} reimplementation will then be executed
+ in a separate thread.
+
+ Creating threads is explained in more detail in the QThread
+ documentation.
+
+ Note that QCoreApplication::exec() must always be called from the
+ main thread (the thread that executes \c{main()}), not from a
+ QThread. In GUI applications, the main thread is also called the
+ GUI thread because it's the only thread that is allowed to
+ perform GUI-related operations.
+*/
- To start the thread, our thread object needs to be instantiated. The
- \l{QThread::}{start()} method creates a new thread and calls the
- reimplemented \l{QThread::}{run()} method in this new thread. Right after
- \l{QThread::}{start()} is called, two program counters walk through the
- program code. The main function starts with only the GUI thread running and
- it should terminate with only the GUI thread running. Exiting the program
- when another thread is still busy is a programming error, and therefore,
- wait is called which blocks the calling thread until the
- \l{QThread::}{run()} method has completed.
+/*!
+ \page threads-synchronizing.html
+ \title Synchronizing Threads
+
+ \previouspage Starting Threads with QThread
+ \contentspage Thread Support in Qt
+ \nextpage Reentrancy and Thread-Safety
+
+ The QMutex, QReadWriteLock, QSemaphore, and QWaitCondition
+ classes provide means to synchronize threads. While the main idea
+ with threads is that they should be as concurrent as possible,
+ there are points where threads must stop and wait for other
+ threads. For example, if two threads try to access the same
+ global variable simultaneously, the results are usually
+ undefined.
+
+ QMutex provides a mutually exclusive lock, or mutex. At most one
+ thread can hold the mutex at any time. If a thread tries to
+ acquire the mutex while the mutex is already locked, the thread will
+ be put to sleep until the thread that currently holds the mutex
+ unlocks it. Mutexes are often used to protect accesses to shared
+ data (i.e., data that can be accessed from multiple threads
+ simultaneously). In the \l{Reentrancy and Thread-Safety} section
+ below, we will use it to make a class thread-safe.
+
+ QReadWriteLock is similar to QMutex, except that it distinguishes
+ between "read" and "write" access to shared data and allows
+ multiple readers to access the data simultaneously. Using
+ QReadWriteLock instead of QMutex when it is possible can make
+ multithreaded programs more concurrent.
+
+ QSemaphore is a generalization of QMutex that protects a certain
+ number of identical resources. In contrast, a mutex protects
+ exactly one resource. The \l{threads/semaphores}{Semaphores}
+ example shows a typical application of semaphores: synchronizing
+ access to a circular buffer between a producer and a consumer.
+
+ QWaitCondition allows a thread to wake up other threads when some
+ condition has been met. One or many threads can block waiting for
+ a QWaitCondition to set a condition with
+ \l{QWaitCondition::wakeOne()}{wakeOne()} or
+ \l{QWaitCondition::wakeAll()}{wakeAll()}. Use
+ \l{QWaitCondition::wakeOne()}{wakeOne()} to wake one randomly
+ selected event or \l{QWaitCondition::wakeAll()}{wakeAll()} to
+ wake them all. The \l{threads/waitconditions}{Wait Conditions}
+ example shows how to solve the producer-consumer problem using
+ QWaitCondition instead of QSemaphore.
+
+ Note that Qt's synchronization classes rely on the use of properly
+ aligned pointers. For instance, you cannot use packed classes with
+ MSVC.
+*/
- This is the result of running the code:
+/*!
+ \page threads-reentrancy.html
+ \title Reentrancy and Thread-Safety
- \badcode
- hello from GUI thread 3079423696
- hello from worker thread 3076111216
- \endcode
+ \keyword reentrant
+ \keyword thread-safe
+ \previouspage Synchronizing Threads
+ \contentspage Thread Support in Qt
+ \nextpage Threads and QObjects
- \section2 QObject and Threads
+ Throughout the documentation, the terms \e{reentrant} and
+ \e{thread-safe} are used to mark classes and functions to indicate
+ how they can be used in multithread applications:
- A QObject is said to have a \e{thread affinity} or, in other words, that it
- lives in a certain thread. This means that, at creation time, QObject saves
- a pointer to the current thread. This information becomes relevant when an
- event is posted with \l{QCoreApplication::}{postEvent()}. The event will be
- put in the corresponding thread's event loop. If the thread where the
- QObject lives doesn't have an event loop, the event will never be delivered.
+ \list
+ \o A \e thread-safe function can be called simultaneously from
+ multiple threads, even when the invocations use shared data,
+ because all references to the shared data are serialized.
+ \o A \e reentrant function can also be called simultaneously from
+ multiple threads, but only if each invocation uses its own data.
+ \endlist
- To start an event loop, \l{QThread::}{exec()} must be called inside
- \l{QThread::}{run()}. Thread affinity can be changed using
- \l{QObject::}{moveToThread()}.
+ Hence, a \e{thread-safe} function is always \e{reentrant}, but a
+ \e{reentrant} function is not always \e{thread-safe}.
+
+ By extension, a class is said to be \e{reentrant} if its member
+ functions can be called safely from multiple threads, as long as
+ each thread uses a \e{different} instance of the class. The class
+ is \e{thread-safe} if its member functions can be called safely
+ from multiple threads, even if all the threads use the \e{same}
+ instance of the class.
+
+ \note Qt classes are only documented as \e{thread-safe} if they
+ are intended to be used by multiple threads. If a function is not
+ marked as thread-safe or reentrant, it should not be used from
+ different threads. If a class is not marked as thread-safe or
+ reentrant then a specific instance of that class should not be
+ accessed from different threads.
+
+ \section1 Reentrancy
+
+ C++ classes are often reentrant, simply because they only access
+ their own member data. Any thread can call a member function on an
+ instance of a reentrant class, as long as no other thread can call
+ a member function on the \e{same} instance of the class at the
+ same time. For example, the \c Counter class below is reentrant:
+
+ \snippet doc/src/snippets/threads/threads.cpp 3
+ \snippet doc/src/snippets/threads/threads.cpp 4
+
+ The class isn't thread-safe, because if multiple threads try to
+ modify the data member \c n, the result is undefined. This is
+ because the \c ++ and \c -- operators aren't always atomic.
+ Indeed, they usually expand to three machine instructions:
+
+ \list 1
+ \o Load the variable's value in a register.
+ \o Increment or decrement the register's value.
+ \o Store the register's value back into main memory.
+ \endlist
- As mentioned above, developers must always be careful when calling objects'
- methods from other threads. 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.
+ If thread A and thread B load the variable's old value
+ simultaneously, increment their register, and store it back, they
+ end up overwriting each other, and the variable is incremented
+ only once!
+
+ \section1 Thread-Safety
+
+ Clearly, the access must be serialized: Thread A must perform
+ steps 1, 2, 3 without interruption (atomically) before thread B
+ can perform the same steps; or vice versa. An easy way to make
+ the class thread-safe is to protect all access to the data
+ members with a QMutex:
+
+ \snippet doc/src/snippets/threads/threads.cpp 5
+ \snippet doc/src/snippets/threads/threads.cpp 6
+
+ The QMutexLocker class automatically locks the mutex in its
+ constructor and unlocks it when the destructor is invoked, at the
+ end of the function. Locking the mutex ensures that access from
+ different threads will be serialized. The \c mutex data member is
+ declared with the \c mutable qualifier because we need to lock
+ and unlock the mutex in \c value(), which is a const function.
+
+ \section1 Notes on Qt Classes
+
+ Many Qt classes are \e{reentrant}, but they are not made
+ \e{thread-safe}, because making them thread-safe would incur the
+ extra overhead of repeatedly locking and unlocking a QMutex. For
+ example, QString is reentrant but not thread-safe. You can safely
+ access \e{different} instances of QString from multiple threads
+ simultaneously, but you can't safely access the \e{same} instance
+ of QString from multiple threads simultaneously (unless you
+ protect the accesses yourself with a QMutex).
+
+ Some Qt classes and functions are thread-safe. These are mainly
+ the thread-related classes (e.g. QMutex) and fundamental functions
+ (e.g. QCoreApplication::postEvent()).
+
+ \note Terminology in the multithreading domain isn't entirely
+ standardized. POSIX uses definitions of reentrant and thread-safe
+ that are somewhat different for its C APIs. When using other
+ object-oriented C++ class libraries with Qt, be sure the
+ definitions are understood.
+*/
- 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.
+/*!
+ \page threads-qobject.html
+ \title Threads and QObjects
- The anatomy of QThread is quite interesting:
+ \previouspage Reentrancy and Thread Safety
+ \contentspage Thread Support in Qt
+ \nextpage Concurrent Programming
+
+ QThread inherits QObject. It emits signals to indicate that the
+ thread started or finished executing, and provides a few slots as
+ well.
+
+ More interesting is that \l{QObject}s can be used in multiple
+ threads, emit signals that invoke slots in other threads, and
+ post events to objects that "live" in other threads. This is
+ possible because each thread is allowed to have its own event
+ loop.
+
+ \section1 QObject Reentrancy
+
+ QObject is reentrant. Most of its non-GUI subclasses, such as
+ QTimer, QTcpSocket, QUdpSocket, QFtp, and QProcess, are also
+ reentrant, making it possible to use these classes from multiple
+ threads simultaneously. Note that these classes are designed to be
+ created and used from within a single thread; creating an object
+ in one thread and calling its functions from another thread is not
+ guaranteed to work. There are three constraints to be aware of:
\list
- \o QThread does not live in the new thread where \l{QThread::}{run()} is
- executed. It lives in the old thread.
- \o Most QThread methods are the thread's control interface and are meant to
- be called from the old thread. Do not move this interface to the newly
- created thread using \l{QObject::}{moveToThread()}; i.e., calling
- \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
- practice.
- \o \l{QThread::}{exec()} and the static methods
- \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
- \l{QThread::}{sleep()} are meant to be called from the newly created
- thread.
- \o Additional members defined in the QThread subclass are
- accessible by both threads. The developer is responsible for
- coordinating access. A typical strategy is to set the members before
- \l{QThread::}{start()} is called. Once the worker thread is running,
- the main thread should not touch the additional members anymore. After
- the worker has terminated, the main thread can access the additional
- members again. This is a convenient strategy for passing parameters to a
- thread before it is started as well as for collecting the result once it
- has terminated.
+ \o \e{The child of a QObject must always be created in the thread
+ where the parent was created.} This implies, among other
+ things, that you should never pass the QThread object (\c
+ this) as the parent of an object created in the thread (since
+ the QThread object itself was created in another thread).
+
+ \o \e{Event driven objects may only be used in a single thread.}
+ Specifically, this applies to the \l{timers.html}{timer
+ mechanism} and the \l{QtNetwork}{network module}. For example,
+ you cannot start a timer or connect a socket in a thread that
+ is not the \l{QObject::thread()}{object's thread}.
+
+ \o \e{You must ensure that all objects created in a thread are
+ deleted before you delete the QThread.} This can be done
+ easily by creating the objects on the stack in your
+ \l{QThread::run()}{run()} implementation.
\endlist
- A QObject's parent must always be in the same thread. This has a surprising
- consequence for objects generated within the \l{QThread::}{run()} method:
-
- \code
- void HelloThread::run()
- {
- QObject *object1 = new QObject(this); //error, parent must be in the same thread
- QObject object2; // OK
- QSharedPointer <QObject> object3(new QObject); // OK
- }
- \endcode
-
- \section2 Using a Mutex to Protect the Integrity of Data
-
- A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
- methods and remembers if it is already locked. A mutex is designed to be
- called from multiple threads. \l{QMutex::}{lock()} returns immediately if
- the mutex is not locked. The next call from another thread will find the
- mutex in a locked state and then \l{QMutex::}{lock()} will block the thread
- until the other thread calls \l{QMutex::}{unlock()}. This functionality can
- make sure that a code section will be executed by only one thread at a time.
-
- The following line sketches how a mutex can be used to make a method
- thread-safe:
-
- \code
- void Worker::work()
- {
- this->mutex.lock(); // first thread can pass, other threads will be blocked here
- doWork();
- this->mutex.unlock();
- }
- \endcode
-
- What happens if one thread does not unlock a mutex? The result can be a
- frozen application. In the example above, an exception might be thrown and
- \c{mutex.unlock()} will never be reached. To prevent problems like this,
- QMutexLocker should be used.
-
- \code
- void Worker::work()
- {
- QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope
- doWork();
- }
- \endcode
-
- This looks easy, but mutexes introduce a new class of problems: deadlocks.
- A deadlock happens when a thread waits for a mutex to become unlocked, but
- the mutex remains locked because the owning thread is waiting for the first
- thread to unlock it. The result is a frozen application. Mutexes can be
- used to make a method thread safe. Most Qt methods aren't thread safe
- because there is always a performance penalty when using mutexes.
-
- It isn't always possible to lock and unlock a mutex in a method. Sometimes
- the need to lock spans several calls. For example, modifying a container
- with an iterator requires a sequence of several calls which should not be
- interrupted by other threads. In such a scenario, locking can be achieved
- with a mutex that is kept outside of the object to be manipulated. With an
- external mutex, the duration of locking can be adjusted to the needs of the
- operation. One disadvantage is that external mutexes aid locking, but do
- not enforce it because users of the object may forget to use it.
-
- \section2 Using the Event Loop to Prevent Data Corruption
-
- The event loops of Qt are a very valuable tool for inter-thread
- communication. Every thread may have its own event loop. A safe way of
- calling a slot in another thread is by placing that call in another
- thread's event loop. This ensures that the target object finishes the
- method that is currently running before another method is started.
-
- So how is it possible to put a method invocation in an event loop? Qt has
- two ways of doing this. One way is via queued signal-slot connections; the
- other way is to post an event with QCoreApplication::postEvent(). A queued
- signal-slot connection is a signal slot connection that is executed
- asynchronously. The internal implementation is based on posted events. The
- arguments of the signal are put into the event loop and the signal method
- returns immediately.
-
- The connected slot will be executed at a time which depends on what else is
- in the event loop.
-
- Communication via the event loop eliminates the deadlock problem we face
- when using mutexes. This is why we recommend using the event loop rather
- than locking an object using a mutex.
-
- \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
-
- This tutorial comes with examples for Qt's three basic ways of working with
- threads. Two more examples show how to communicate with a running thread
- and how a QObject can be placed in another thread, providing service to the
- main thread.
+ Although QObject is reentrant, the GUI classes, notably QWidget
+ and all its subclasses, are not reentrant. They can only be used
+ from the main thread. As noted earlier, QCoreApplication::exec()
+ must also be called from that thread.
+
+ In practice, the impossibility of using GUI classes in other
+ threads than the main thread can easily be worked around by
+ putting time-consuming operations in a separate worker thread and
+ displaying the results on screen in the main thread when the
+ worker thread is finished. This is the approach used for
+ implementing the \l{threads/mandelbrot}{Mandelbrot} and
+ the \l{network/blockingfortuneclient}{Blocking Fortune Client}
+ example.
+
+ \section1 Per-Thread Event Loop
+
+ Each thread can have its own event loop. The initial thread
+ starts its event loops using QCoreApplication::exec(); other
+ threads can start an event loop using QThread::exec(). Like
+ QCoreApplication, QThread provides an
+ \l{QThread::exit()}{exit(int)} function and a
+ \l{QThread::quit()}{quit()} slot.
+
+ An event loop in a thread makes it possible for the thread to use
+ certain non-GUI Qt classes that require the presence of an event
+ loop (such as QTimer, QTcpSocket, and QProcess). It also makes it
+ possible to connect signals from any threads to slots of a
+ specific thread. This is explained in more detail in the
+ \l{Signals and Slots Across Threads} section below.
+
+ \image threadsandobjects.png Threads, objects, and event loops
+
+ A QObject instance is said to \e live in the thread in which it
+ is created. Events to that object are dispatched by that thread's
+ event loop. The thread in which a QObject lives is available using
+ QObject::thread().
+
+ Note that for QObjects that are created before QApplication,
+ QObject::thread() returns zero. This means that the main thread
+ will only handle posted events for these objects; other event
+ processing is not done at all for objects with no thread. Use the
+ QObject::moveToThread() function to change the thread affinity for
+ an object and its children (the object cannot be moved if it has a
+ parent).
+
+ Calling \c delete on a QObject from a thread other than the one
+ that \e owns the object (or accessing the object in other ways) is
+ unsafe, unless you guarantee that the object isn't processing
+ events at that moment. Use QObject::deleteLater() instead, and a
+ \l{QEvent::DeferredDelete}{DeferredDelete} event will be posted,
+ which the event loop of the object's thread will eventually pick
+ up. By default, the thread that \e owns a QObject is the thread
+ that \e creates the QObject, but not after QObject::moveToThread()
+ has been called.
+
+ If no event loop is running, events won't be delivered to the
+ object. For example, if you create a QTimer object in a thread but
+ never call \l{QThread::exec()}{exec()}, the QTimer will never emit
+ its \l{QTimer::timeout()}{timeout()} signal. Calling
+ \l{QObject::deleteLater()}{deleteLater()} won't work
+ either. (These restrictions apply to the main thread as well.)
+
+ You can manually post events to any object in any thread at any
+ time using the thread-safe function
+ QCoreApplication::postEvent(). The events will automatically be
+ dispatched by the event loop of the thread where the object was
+ created.
+
+ Event filters are supported in all threads, with the restriction
+ that the monitoring object must live in the same thread as the
+ monitored object. Similarly, QCoreApplication::sendEvent()
+ (unlike \l{QCoreApplication::postEvent()}{postEvent()}) can only
+ be used to dispatch events to objects living in the thread from
+ which the function is called.
+
+ \section1 Accessing QObject Subclasses from Other Threads
+
+ QObject and all of its subclasses are not thread-safe. This
+ includes the entire event delivery system. It is important to keep
+ in mind that the event loop may be delivering events to your
+ QObject subclass while you are accessing the object from another
+ thread.
+
+ If you are calling a function on an QObject subclass that doesn't
+ live in the current thread and the object might receive events,
+ you must protect all access to your QObject subclass's internal
+ data with a mutex; otherwise, you may experience crashes or other
+ undesired behavior.
+
+ Like other objects, QThread objects live in the thread where the
+ object was created -- \e not in the thread that is created when
+ QThread::run() is called. It is generally unsafe to provide slots
+ in your QThread subclass, unless you protect the member variables
+ with a mutex.
+
+ On the other hand, you can safely emit signals from your
+ QThread::run() implementation, because signal emission is
+ thread-safe.
+
+ \section1 Signals and Slots Across Threads
+
+ Qt supports these signal-slot connection types:
\list
- \o Using QThread as shown \l{Qt thread basics}{above}
- \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool}
- \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent}
- \o \l{Example 3: Clock}{Communication with the GUI thread}
- \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread
- provides service to the main thread}
+
+ \o \l{Qt::AutoConnection}{Auto Connection} (default) If the signal is
+ emitted in the thread which the receiving object has affinity then
+ the behavior is the same as the Direct Connection. Otherwise,
+ the behavior is the same as the Queued Connection."
+
+ \o \l{Qt::DirectConnection}{Direct Connection} The slot is invoked
+ immediately, when the signal is emitted. The slot is executed
+ in the emitter's thread, which is not necessarily the
+ receiver's thread.
+
+ \o \l{Qt::QueuedConnection}{Queued Connection} The slot is invoked
+ when control returns to the event loop of the receiver's
+ thread. The slot is executed in the receiver's thread.
+
+ \o \l{Qt::BlockingQueuedConnection}{Blocking Queued Connection}
+ The slot is invoked as for the Queued Connection, except the
+ current thread blocks until the slot returns. \note Using this
+ type to connect objects in the same thread will cause deadlock.
+
+ \o \l{Qt::UniqueConnection}{Unique Connection} The behavior is the
+ same as the Auto Connection, but the connection is made only if
+ it does not duplicate an existing connection. i.e., if the same
+ signal is already connected to the same slot for the same pair
+ of objects, then the connection is not made and connect()
+ returns false.
+
\endlist
- The following examples can all be compiled and run independently. The source can
- be found in the examples directory: examples/tutorials/threads/
-
- \section2 Example 1: Using the Thread Pool
-
- Creating and destroying threads frequently can be expensive. To avoid the
- cost of thread creation, a thread pool can be used. A thread pool is a
- place where threads can be parked and fetched. We can write the same
- "hello thread" program as \l{Qt Thread Basics}{above} using the global
- thread pool. We derive a class from QRunnable. The code we want to run in
- another thread needs to be placed in the reimplemented QRunnable::run()
- method.
-
- \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1
-
- We instantiate Work in main(), locate the global thread pool and use the
- QThreadPool::start() method. Now the thread pool runs our worker in another
- thread. Using the thread pool has a performance advantage because threads
- are not destroyed after they have finished running. They are kept in a pool
- and wait to be used again later.
-
- \section2 Example 2: Using QtConcurrent
-
- \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1
-
- We write a global function hello() to implement the work. QtConcurrent::run()
- is used to run the function in another thread. The result is a QFuture.
- QFuture provides a method called \l{QFuture::}{waitForFinished()}, which
- blocks until the calculation is completed. The real power of QtConcurrent
- becomes visible when data can be made available in a container. QtConcurrent
- provides several functions that are able to process itemized data on all
- available cores simultaneously. The use of QtConcurrent is very similar to
- applying an STL algorithm to an STL container.
- \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and
- clear example about how a container of images can be scaled on all available
- cores. The image scaling example uses the blocking variants of the functions
- used. For every blocking function there is also a non-blocking, asynchronous
- counterpart. Getting results asynchronously is implemented with QFuture and
- QFutureWatcher.
-
- \section2 Example 3: Clock
-
- \image thread_clock.png "clock"
-
- We want to produce a clock application. The application has a GUI and a
- worker thread. The worker thread checks every 10 milliseconds what time it
- is. If the formatted time has changed, the result will be sent to the GUI
- thread where it is displayed.
-
- Of course, this is an overly complicated way of designing a clock and,
- actually, a separate thread is unnecessary. We would be better off placing
- the timer in the main thread because the calculation made in the timer slot
- is very short-lived. This example is purely for instructional use and shows
- how to communicate from a worker thread to a GUI thread. Note that
- communication in this direction is easy. We only need to add a signal
- to QThread and make a queued signal/slot connection to the main thread.
- Communication from the GUI to the worker thread is shown in the next
- example.
+ The connection type can be specified by passing an additional
+ argument to \l{QObject::connect()}{connect()}. Be aware that
+ using direct connections when the sender and receiver live in
+ different threads is unsafe if an event loop is running in the
+ receiver's thread, for the same reason that calling any function
+ on an object living in another thread is unsafe.
+
+ QObject::connect() itself is thread-safe.
+
+ The \l{threads/mandelbrot}{Mandelbrot} example uses a queued
+ connection to communicate between a worker thread and the main
+ thread. To avoid freezing the main thread's event loop (and, as a
+ consequence, the application's user interface), all the
+ Mandelbrot fractal computation is done in a separate worker
+ thread. The thread emits a signal when it is done rendering the
+ fractal.
+
+ Similarly, the \l{network/blockingfortuneclient}{Blocking Fortune
+ Client} example uses a separate thread for communicating with
+ a TCP server asynchronously.
+*/
- \snippet examples/tutorials/threads/clock/main.cpp 1
+/*!
+ \page threads-qtconcurrent.html
+ \title Concurrent Programming
+
+ \previouspage Threads and QObjects
+ \contentspage Thread Support in Qt
+ \nextpage Thread-Support in Qt Modules
+
+ \target qtconcurrent intro
+
+ The QtConcurrent namespace provides high-level APIs that make it
+ possible to write multi-threaded programs without using low-level
+ threading primitives such as mutexes, read-write locks, wait
+ conditions, or semaphores. Programs written with QtConcurrent
+ automatically adjust the number of threads used according to the
+ number of processor cores available. This means that applications
+ written today will continue to scale when deployed on multi-core
+ systems in the future.
+
+ QtConcurrent includes functional programming style APIs for
+ parallel list processing, including a MapReduce and FilterReduce
+ implementation for shared-memory (non-distributed) systems, and
+ classes for managing asynchronous computations in GUI
+ applications:
- We've connected the \c clockThread with the label. The connection must be a
- queued signal-slot connection because we want to put the call in the event
- loop.
+ \list
- \snippet examples/tutorials/threads/clock/clockthread.h 1
+ \o QtConcurrent::map() applies a function to every item in a container,
+ modifying the items in-place.
- We have derived a class from QThread and declared the \c sendTime() signal.
+ \o QtConcurrent::mapped() is like map(), except that it returns a new
+ container with the modifications.
- \snippet examples/tutorials/threads/clock/clockthread.cpp 1
+ \o QtConcurrent::mappedReduced() is like mapped(), except that the
+ modified results are reduced or folded into a single result.
- The trickiest part of this example is that the timer is connected to its
- slot via a direct connection. A default connection would produce a queued
- signal-slot connection because the connected objects live in different
- threads; remember that QThread does not live in the thread it creates.
+ \o QtConcurrent::filter() removes all items from a container based on the
+ result of a filter function.
- Still it is safe to access ClockThread::timerHit() from the worker thread
- because ClockThread::timerHit() is private and only touches local variables
- and a private member that isn't touched by public methods.
- QDateTime::currentDateTime() isn't marked as thread-safe in Qt
- documentation, however we can get away with using it in this small
- example because we know that the QDateTime::currentDateTime() static
- method isn't used in any other threads.
+ \o QtConcurrent::filtered() is like filter(), except that it returns a new
+ container with the filtered results.
- \section2 Example 4: A Permanent Thread
+ \o QtConcurrent::filteredReduced() is like filtered(), except that the
+ filtered results are reduced or folded into a single result.
- This example shows how it is possible to have a QObject in a worker thread
- that accepts requests from the GUI thread, does polling using a timer and
- continuously reports results back to the GUI thread. The actual work
- including the polling must be implemented in a class derived from QObject.
- We have called this class \c WorkerObject in the code shown below. The
- thread-specific code is hidden in a class called \c Thread, derived from
- QThread.
- \c Thread has two additional public members. The \c launchWorker() member
- takes the worker object and moves it to another thread with a started event
- loop.
- The call blocks for a very short moment until the thread creation operation
- is completed, allowing the worker object to be used again on the next line.
- The \c Thread class's code is short but somewhat involved, so we only show
- how to use the class.
+ \o QtConcurrent::run() runs a function in another thread.
- \snippet examples/tutorials/threads/movedobject/main.cpp 1
+ \o QFuture represents the result of an asynchronous computation.
- QMetaObject::invokeMethod() calls a slot via the event loop. The worker
- object's methods should not be called directly after the object has been
- moved to another thread. We let the worker thread do some work and polling,
- and use a timer to shut the application down after 3 seconds. Shutting the
- worker down needs some care. We call \c{Thread::stop()} to exit the event
- loop. We wait for the thread to terminate and, after this has occurred, we
- delete the worker.
+ \o QFutureIterator allows iterating through results available via QFuture.
- \section1 Digging Deeper
+ \o QFutureWatcher allows monitoring a QFuture using signals-and-slots.
- 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:
+ \o QFutureSynchronizer is a convenience class that automatically
+ synchronizes several QFutures.
- \list
- \o Good video tutorials about threads with Qt can be found in the material
- from the \l{Training Day at Qt Developer Days 2009}.
- \o The \l{Thread Support in Qt} document is a good starting point into
- the reference documentation.
- \o Qt comes with several additional examples for
- \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
- \o 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
+
+ Qt Concurrent supports several STL-compatible container and iterator types,
+ but works best with Qt containers that have random-access iterators, such as
+ QList or QVector. The map and filter functions accept both containers and begin/end iterators.
+
+ STL Iterator support overview:
+
+ \table
+ \header
+ \o Iterator Type
+ \o Example classes
+ \o Support status
+ \row
+ \o Input Iterator
+ \o
+ \o Not Supported
+ \row
+ \o Output Iterator
+ \o
+ \o Not Supported
+ \row
+ \o Forward Iterator
+ \o std::slist
+ \o Supported
+ \row
+ \o Bidirectional Iterator
+ \o QLinkedList, std::list
+ \o Supported
+ \row
+ \o Random Access Iterator
+ \o QList, QVector, std::vector
+ \o Supported and Recommended
+ \endtable
+
+ Random access iterators can be faster in cases where Qt Concurrent is iterating
+ over a large number of lightweight items, since they allow skipping to any point
+ in the container. In addition, using random access iterators allows Qt Concurrent
+ to provide progress information trough QFuture::progressValue() and QFutureWatcher::
+ progressValueChanged().
+
+ The non in-place modifying functions such as mapped() and filtered() makes a
+ copy of the container when called. If you are using STL containers this copy operation
+ might take some time, in this case we recommend specifying the begin and end iterators
+ for the container instead.
+*/
+
+/*!
+ \page threads-modules.html
+ \title Thread-Support in Qt Modules
+
+ \previouspage Concurrent Programming
+ \contentspage Thread Support in Qt
+
+ \section1 Threads and the SQL Module
+
+ A connection can only be used from within the thread that created it.
+ Moving connections between threads or creating queries from a different
+ thread is not supported.
+
+ In addition, the third party libraries used by the QSqlDrivers can impose
+ further restrictions on using the SQL Module in a multithreaded program.
+ Consult the manual of your database client for more information
+
+ \section1 Painting in Threads
+
+ QPainter can be used in a thread to paint onto QImage, QPrinter, and
+ QPicture paint devices. Painting onto QPixmaps and QWidgets is \e not
+ supported. On Mac OS X the automatic progress dialog will not be
+ displayed if you are printing from outside the GUI thread.
+
+ Any number of threads can paint at any given time, however only
+ one thread at a time can paint on a given paint device. In other
+ words, two threads can paint at the same time if each paints onto
+ separate QImages, but the two threads cannot paint onto the same
+ QImage at the same time.
+
+ Note that on X11 systems without FontConfig support, Qt cannot
+ render text outside of the GUI thread. You can use the
+ QFontDatabase::supportsThreadedFontRendering() function to detect
+ whether or not font rendering can be used outside the GUI thread.
+
+ \section1 Threads and Rich Text Processing
+
+ The QTextDocument, QTextCursor, and \link richtext.html all
+ related classes\endlink are reentrant.
+
+ Note that a QTextDocument instance created in the GUI thread may
+ contain QPixmap image resources. Use QTextDocument::clone() to
+ create a copy of the document, and pass the copy to another thread for
+ further processing (such as printing).
+
+ \section1 Threads and the SVG module
+
+ The QSvgGenerator and QSvgRenderer classes in the QtSvg module
+ are reentrant.
+
+ \section1 Threads and Implicitly Shared Classes
+
+ Qt uses an optimization called \l{implicit sharing} for many of
+ its value class, notably QImage and QString. Beginning with Qt 4,
+ implicit shared classes can safely be copied across threads, like
+ any other value classes. They are fully
+ \l{Reentrancy and Thread-Safety}{reentrant}. The implicit sharing
+ is really \e implicit.
+
+ In many people's minds, implicit sharing and multithreading are
+ incompatible concepts, because of the way the reference counting
+ is typically done. Qt, however, uses atomic reference counting to
+ ensure the integrity of the shared data, avoiding potential
+ corruption of the reference counter.
+
+ Note that atomic reference counting does not guarantee
+ \l{Reentrancy and Thread-Safety}{thread-safety}. Proper locking should be used
+ when sharing an instance of an implicitly shared class between
+ threads. This is the same requirement placed on all
+ \l{Reentrancy and Thread-Safety}{reentrant} classes, shared or not. Atomic reference
+ counting does, however, guarantee that a thread working on its
+ own, local instance of an implicitly shared class is safe. We
+ recommend using \l{Signals and Slots Across Threads}{signals and
+ slots} to pass data between threads, as this can be done without
+ the need for any explicit locking.
+
+ To sum it up, implicitly shared classes in Qt 4 are really \e
+ implicitly shared. Even in multithreaded applications, you can
+ safely use them as if they were plain, non-shared, reentrant
+ value-based classes.
*/
projects / profile / ivi / qtbase.git / commitdiff