QThread documentation: do not discourage the reimplementation of QThread

The new QThread documentation now really discourage to reimplement
QThread. But in fact, there are many cases where it is perfectly fine.
And the example given is even a case where using worker object is wrong.
The examle even contains a leak since the thread will never stop and
will even leak.

This changes put back some sentences from before commit
207f588b6896cbe72745037dc1cb0a3aef1cf6d0.

The sample code has been re-writen. Notice how reimpementing run takes
less lines of code, less runtime overhead, no leaks, and also is more
complete than the previous example.

This is a modified backport of
qtbase commit 91e12dca757a8ef5c4691b70eb80db61a9d47e83

Change-Id: I4932aef00307a6cf91d57d632a02b8a85e5e8845
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>

1 files changed, 24 insertions, 38 deletions

diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp
index 07de812..53e4d5e 100644
--- a/src/corelib/thread/qthread.cpp
+++ b/src/corelib/thread/qthread.cpp
@@ -203,21 +203,38 @@ QThreadPrivate::~QThreadPrivate()
     \ingroup thread
 
     A QThread object manages one thread of control within the
-    program. To make code run in a separate thread, simply create a
-    QThread, change the thread affinity of the QObject(s) that
-    contain the code, and start() the new event loop. For example:
+    program. QThreads begin executing in run(). By default, run() starts the
+    event loop by calling exec() and runs a Qt event loop inside the thread.
 
-    \snippet doc/src/snippets/code/src_corelib_thread_qthread.cpp 0
+    You can use worker objects by moving them to the thread using
+    QObject::moveToThread().
+
+    \snippet doc/src/snippets/code/src_corelib_thread_qthread.cpp worker
 
     The code inside the Worker's slot would then execute in a
-    separate thread. In this example, the QThread triggers the
-    Worker's doWork() slot upon starting, and frees the Worker's
-    memory upon terminating. However, you are free to connect the
+    separate thread. However, you are free to connect the
     Worker's slots to any signal, from any object, in any thread. It
     is safe to connect signals and slots across different threads,
     thanks to a mechanism called \l{Qt::QueuedConnection}{queued
     connections}.
 
+    Another way to make code run in a separate thread, is to subclass QThread
+    and reimplement run(). For example:
+
+    \snippet code/src_corelib_thread_qthread.cpp reimpl-run
+
+    In that example, the thread will exit after the run function has returned.
+    There will not be any event loop running in the thread unless you call
+    exec().
+
+    It is important to remember that a QThread object usually lives
+    in the thread where it was created, not in the thread that it
+    manages. This oft-overlooked detail means that a QThread's slots
+    will be executed in the context of its home thread, not in the
+    context of the thread it is managing. For this reason,
+    implementing new slots in a QThread subclass is error-prone and
+    discouraged.
+
     \note If you interact with an object, using any technique other
     than queued signal/slot connections (e.g. direct function calls),
     then the usual multithreading precautions need to be taken.
@@ -225,7 +242,6 @@ QThreadPrivate::~QThreadPrivate()
     \note It is not possible to change the thread affinity of GUI
     objects; they must remain in the main thread.
 
-
     \section1 Managing threads
 
     QThread will notifiy you via a signal
@@ -260,28 +276,6 @@ QThreadPrivate::~QThreadPrivate()
     \l{Mandelbrot Example}, as that is the name of the QThread subclass).
     Note that this is currently not available with release builds on Windows.
 
-    \section1 Subclassing QThread
-
-    Subclassing QThread is unnecessary for most purposes, since
-    QThread provides fully-functional thread management capabilities.
-    Nonetheless, QThread can be subclassed if you wish to implement
-    advanced thread management. This is done by adding new member
-    functions to the subclass, and/or by reimplementing run().
-    QThread's run() function is analogous to an application's main()
-    function -- it is executed when the thread is started, and the
-    thread will end when it returns.
-
-    \note Prior to Qt 4.4, the only way to use QThread for parallel
-    processing was to subclass it and implement the processing code
-    inside run(). This approach is now considered \b {bad practice};
-    a QThread should only manage a thread, not process data.
-
-    If you require event handling and signal/slot connections to
-    work in your thread, and if you reimplement run(), you must
-    explicitly call exec() at the end of your reimplementation:
-
-    \snippet doc/src/snippets/code/src_corelib_thread_qthread.cpp 1
-
     QThread also provides static, platform independent sleep
     functions: sleep(), msleep(), and usleep() allow full second,
     millisecond, and microsecond resolution respectively.
@@ -291,14 +285,6 @@ QThreadPrivate::~QThreadPrivate()
     wait(), consider listening for the finished() signal. Instead of
     the sleep() functions, consider using QTimer.
 
-    It is important to remember that a QThread object usually lives
-    in the thread where it was created, not in the thread that it
-    manages. This oft-overlooked detail means that a QThread's slots
-    will be executed in the context of its home thread, not in the
-    context of the thread it is managing. For this reason,
-    implementing new slots in a QThread subclass is error-prone and
-    discouraged.
-
     \sa {Thread Support in Qt}, QThreadStorage, QMutex, QSemaphore, QWaitCondition,
         {Mandelbrot Example}, {Semaphores Example}, {Wait Conditions Example}
 */