Doc: Move threading overviews from qtbase.git to qtdoc.git

- This topic is  relevant to multiple modules, as illustrated by the
  "Thread-Support in Qt Modules" page. Multithreading can be done in
  both C++ and QML.
- Moving also fixes links to QML-related pages.
- Snippets are copied, not moved. QThreadStorage docs need them.
- QDoc: "DEPENDS += qtdoc" added to keep the "\reentrant" command
  working. It creates a link to the "reentrant" keyword.

Change-Id: I2cdf6139e62d66911561c30fcca7aab160a694b1
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

1 files changed, 0 insertions, 244 deletions

diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc
deleted file mode 100644
index 2206899460..0000000000
--- a/src/corelib/doc/src/threads-basics.qdoc
+++ /dev/null
@@ -1,244 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Digia.  For licensing terms and
-** conditions see http://qt.digia.com/licensing.  For further information
-** use the contact form at http://qt.digia.com/contact-us.
-**
-** GNU Free Documentation License Usage
-** 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.  Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $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 -- 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
-    \li Make processing faster by making use of multicore processors.
-    \li 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
-        \li Alternative
-        \li Comment
-    \row
-        \li QEventLoop::processEvents()
-        \li 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
-        \li QTimer
-        \li 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
-        \li QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
-        \li 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. The QtConcurrent module 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?
-
-    See the \l{Multithreading Technologies in Qt} page for an introduction to the
-    different approaches to multithreading to Qt, and for guidelines on how to
-    choose among them.
-
-
-    \section1 Qt Thread Basics
-
-    The following sections describe how QObjects interact with threads, how
-    programs can safely access data from multiple threads, and how asynchronous
-    execution produces results without blocking a thread.
-
-    \section2 QObject and Threads
-
-    As mentioned above, developers must always be careful when calling objects'
-    methods from other threads. \l{QObject#Thread Affinity}{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.
-
-    \section2 Protecting the Integrity of Data
-
-    When writing a multithread application, extra care must be taken to avoid
-    data corruption. See \l{Synchronizing Threads} for a discussion on how to
-    use threads safely.
-
-    \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
-
-    Qt comes with several examples for using threads. See the class references
-    for QThread and QThreadPool for simple examples. See the \l{Threading and
-    Concurrent Programming Examples} page for more advanced ones.
-
-    \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
-    \li Good video tutorials about threads with Qt can be found in the material
-       from the \l{Training Day at Qt Developer Days 2009}.
-    \li The \l{Thread Support in Qt} document is a good starting point into
-       the reference documentation.
-    \li Qt comes with several additional examples for
-       \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
-    \li 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
-*/