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, 54 insertions, 26 deletions

diff --git a/doc/src/snippets/code/src_corelib_thread_qthread.cpp b/doc/src/snippets/code/src_corelib_thread_qthread.cpp
index 35f1e34..408f90f 100644
--- a/doc/src/snippets/code/src_corelib_thread_qthread.cpp
+++ b/doc/src/snippets/code/src_corelib_thread_qthread.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2013 Olivier Goffart <ogoffart@woboq.com>
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -38,41 +38,69 @@
 **
 ****************************************************************************/
 
-//! [0]
-class Worker : public QObject
+#include <QtCore/QThread>
+class MyObject;
+
+//! [reimpl-run]
+class WorkerThread : public QThread
 {
     Q_OBJECT
-
-public slots:
-    void doWork() {
-        ...
+    void run() {
+        QString result;
+        /* expensive or blocking operation  */
+        emit resultReady(result);
     }
+signals:
+    void resultReady(const QString &s);
 };
 
-void MyObject::putWorkerInAThread()
+void MyObject::startWorkInAThread()
 {
-    Worker *worker = new Worker;
-    QThread *workerThread = new QThread(this);
-
-    connect(workerThread, SIGNAL(started()), worker, SLOT(doWork()));
-    connect(workerThread, SIGNAL(finished()), worker, SLOT(deleteLater()));
-    worker->moveToThread(workerThread);
-
-    // Starts an event loop, and emits workerThread->started()
+    WorkerThread *workerThread = new WorkerThread(this);
+    connect(workerThread, SIGNAL(resultReady(QString)), this, SLOT(handleResults(QString)));
+    connect(workerThread, SIGNAL(finished()), workerThread, SLOT(deleteLater()));
     workerThread->start();
 }
-//! [0]
+//! [reimpl-run]
+
 
-//! [1]
-class AdvancedThreadManager : public QThread
+//! [worker]
+class Worker : public QObject
 {
-protected:
-    void run()
-    {
-        /* ... other code to initialize thread... */
+    Q_OBJECT
+    QThread workerThread;
 
-        // Begin event handling
-        exec();
+public slots:
+    void doWork(const QString &parameter) {
+        // ...
+        emit resultReady(result);
     }
+
+signals:
+    void resultReady(const QString &result);
 };
-//! [1]
+
+class Controller : public QObject
+{
+    Q_OBJECT
+    QThread workerThread;
+public:
+    Controller() {
+        Worker *worker = new Worker;
+        worker->moveToThread(&workerThread);
+        connect(workerThread, SIGNAL(finished()), worker, SLOT(deleteLater()));
+        connect(this, SIGNAL(operate(QString)), worker, SLOT(doWork(QString)));
+        connect(worker, SIGNAL(resultReady(QString)), this, SLOT(handleResults(QString)));
+        workerThread.start();
+    }
+    ~Controller() {
+        workerThread.quit();
+        workerThread.wait();
+    }
+public slots:
+    void handleResults(const QString &);
+signals:
+    void operate(const QString &);
+};
+//! [worker]
+