source: trunk/doc/src/frameworks-technologies/threads.qdoc@ 568

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** 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.1, 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group thread
    \title Threading Classes
*/

/*!
    \page threads.html
    \title Thread Support in Qt
    \brief A detailed discussion of thread handling in Qt.

    \ingroup frameworks-technologies

    \nextpage Starting Threads with QThread

    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.

    \section1 Topics:

    \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

    \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:

    \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

    \section1 The Threading Classes

    These classes are relevant to threaded applications.

    \annotatedlist thread

\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

    \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.
*/

/*!
    \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.
*/

/*!
    \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.
*/

/*!
    \page threads-reentrancy.html
    \title Reentrancy and Thread-Safety
    
    \keyword reentrant
    \keyword thread-safe
    
    \previouspage Synchronizing Threads
    \contentspage Thread Support in Qt
    \nextpage Threads and QObjects

    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:

    \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

    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.

    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

    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.

    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 Qt Classes are only documented as \e{thread-safe} if they
    are intended to be used by multiple threads.

    \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.
*/

/*!
    \page threads-qobject.html