summaryrefslogtreecommitdiffstats
path: root/doc/src/threads.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/threads.qdoc')
-rw-r--r--doc/src/threads.qdoc609
1 files changed, 609 insertions, 0 deletions
diff --git a/doc/src/threads.qdoc b/doc/src/threads.qdoc
new file mode 100644
index 0000000..54bcf2d
--- /dev/null
+++ b/doc/src/threads.qdoc
@@ -0,0 +1,609 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page threads.html
+ \title Thread Support in Qt
+ \ingroup architecture
+ \brief A detailed discussion of thread handling in Qt.
+
+ 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.
+
+ Earlier versions of Qt offered an option to build the library
+ without thread support. Since Qt 4.0, threads are always enabled.
+
+ This document is intended for an audience that has knowledge of,
+ and experience with, multithreaded applications. If you are new
+ to threading see our \l{#reading}{Recommended Reading} list.
+
+ Topics:
+
+ \tableofcontents
+
+ \section1 The Threading Classes
+
+ Qt includes the following thread classes:
+
+ \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
+
+ \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.
+
+ \section2 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
+
+ Then, create an instance of the thread object and call
+ QThread::start(). 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.
+
+ In addition, you must create the QApplication (or
+ QCoreApplication) object before you can create a QThread.
+
+ \section2 Synchronizing Threads
+
+ 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.
+
+ \target qtconcurrent intro
+ \section1 QtConcurrent
+
+ 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:
+
+ \list
+
+ \o QtConcurrent::map() applies a function to every item in a container,
+ modifying the items in-place.
+
+ \o QtConcurrent::mapped() is like map(), except that it returns a new
+ container with the modifications.
+
+ \o QtConcurrent::mappedReduced() is like mapped(), except that the
+ modified results are reduced or folded into a single result.
+
+ \o QtConcurrent::filter() removes all items from a container based on the
+ result of a filter function.
+
+ \o QtConcurrent::filtered() is like filter(), except that it returns a new
+ container with the filtered results.
+
+ \o QtConcurrent::filteredReduced() is like filtered(), except that the
+ filtered results are reduced or folded into a single result.
+
+ \o QtConcurrent::run() runs a function in another thread.
+
+ \o QFuture represents the result of an asynchronous computation.
+
+ \o QFutureIterator allows iterating through results available via QFuture.
+
+ \o QFutureWatcher allows monitoring a QFuture using signals-and-slots.
+
+ \o QFutureSynchronizer is a convenience class that automatically
+ synchronizes several QFutures.
+
+ \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.
+
+ \keyword reentrant
+ \keyword thread-safe
+ \section1 Reentrancy and Thread-Safety
+
+ Throughout the Qt documentation, the terms \e reentrant and \e
+ thread-safe are used to specify how a function can be used in
+ multithreaded applications:
+
+ \list
+ \o A \e reentrant function can be called simultaneously by
+ multiple threads provided that each invocation of the function
+ references unique data.
+ \o A \e thread-safe function can be called simultaneously by
+ multiple threads when each invocation references shared data.
+ All access to the shared data is serialized.
+ \endlist
+
+ By extension, a class is said to be reentrant if each and every
+ one of its functions can be called simultaneously by multiple
+ threads on different instances of the class. Similarly, the class
+ is said to be thread-safe if the functions can be called by
+ different threads on the same instance.
+
+ Classes in the documentation will be documented as thread-safe only
+ if they are intended to be used by multiple threads.
+
+ Note that the terminology in this domain isn't entirely
+ standardized. POSIX uses a somewhat different definition of
+ reentrancy and thread-safety for its C APIs. When dealing with an
+ object-oriented C++ class library such as Qt, the definitions
+ must be adapted.
+
+ Most C++ classes are inherently reentrant, since they typically
+ only reference member data. Any thread can call such a member
+ function on an instance of the class, as long as no other thread
+ is calling a member function on the same instance. 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 C++'s \c ++ and \c -- operators aren't necessarily
+ 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
+
+ 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!
+
+ 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.
+
+ Most Qt classes are reentrant and not thread-safe, to avoid the
+ overhead of repeatedly locking and unlocking a QMutex. For
+ example, QString is reentrant, meaning that you can use it in
+ different threads, but you can't access the same QString object
+ from different threads simultaneously (unless you protect it with
+ a mutex yourself). A few classes and functions are thread-safe;
+ these are mainly thread-related classes such as QMutex, or
+ fundamental functions such as QCoreApplication::postEvent().
+
+ \section1 Threads and QObjects
+
+ 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.
+
+ \section2 QObject Reentrancy
+
+ QObject is reentrant. Most of its non-GUI subclasses, such as
+ QTimer, QTcpSocket, QUdpSocket, QHttp, 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 \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
+
+ 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.
+
+ \section2 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 another thread than the
+ thread where it is created (or accessing the object in other
+ ways) is unsafe unless you can guarantee that the object isn't
+ processing events at the same moment. Use QObject::deleteLater()
+ instead; it will post a
+ \l{QEvent::DeferredDelete}{DeferredDelete} event, which the
+ event loop of the object's thread will eventually pick up.
+
+ 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.
+
+ \section2 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.
+
+ \section2 Signals and Slots Across Threads
+
+ Qt supports three types of signal-slot connections:
+
+ \list
+ \o With \l{Qt::DirectConnection}{direct connections}, the
+ slot gets called immediately when the signal is emitted. The
+ slot is executed in the thread that emitted the signal (which
+ is not necessarily the thread where the receiver object
+ lives).
+
+ \o With \l{Qt::QueuedConnection}{queued connections}, the
+ slot is invoked when control returns to the event loop of the
+ thread to which the object belongs. The slot is executed in
+ the thread where the receiver object lives.
+
+ \o With \l{Qt::AutoConnection}{auto connections} (the default),
+ the behavior is the same as with direct connections if
+ the signal is emitted in the thread where the receiver lives;
+ otherwise, the behavior is that of a queued connection.
+ \endlist
+
+ 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.
+
+ \section1 Threads and Implicit Sharing
+
+ 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{#reentrant}{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{#thread-safe}{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{#reentrant}{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.
+
+ \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 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.
+
+ \target reading
+ \section1 Recommended Reading
+
+ \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
+*/