source: trunk/doc/src/threads.qdoc@ 432

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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
*/