/****************************************************************************

**

** Copyright (C) 2010 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: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 Technology Preview License Agreement accompanying

** this package.

**

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

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $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

    \title Threads and QObjects

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

    Topics:

    \tableofcontents

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

    \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 \l{Qt::AutoConnection}{Auto Connection} (default) The behavior

       is the same as the Direct Connection, if the emitter and

       receiver are in the same thread. The behavior is the same as

       the Queued Connection, if the emitter and receiver are in

       different threads.

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

*/