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

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.

Change-Id: I6cb80826e917dd5ce442ccad2572ec692ccb25ab
Reviewed-by: Andre Somers <andre@familiesomers.nl>
Reviewed-by: Geir Vattekar <geir.vattekar@digia.com>
Reviewed-by: Debao Zhang <hello@debao.me>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 53 insertions, 26 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp
index f0bc759320..c33c8bb48a 100644
--- a/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp
+++ b/src/corelib/doc/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,68 @@
 **
 ****************************************************************************/
 
-//! [0]
-class Worker : public QObject
+#include <QtCore/QThread>
+class MyObject;
+
+//! [reimpl-run]
+class WorkerThread : public QThread
 {
     Q_OBJECT
-
-public slots:
-    void doWork() {
-        ...
+    void run() Q_DECL_OVERRIDE {
+        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, &QThread::started, worker, &Worker::doWork);
-    connect(workerThread, &QThread::finished, worker, &Worker::deleteLater);
-    worker->moveToThread(workerThread);
-
-    // Starts an event loop, and emits workerThread->started()
+    WorkerThread *workerThread = new WorkerThread(this);
+    connect(workerThread, &WorkerThread::resultReady, this, &MyObject::handleResults);
+    connect(workerThread, &WorkerThread::finished, workerThread, &QObject::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);
+};
+
+class Controller : public QObject
+{
+    Q_OBJECT
+    QThread workerThread;
+public:
+    Controller() {
+        Worker *worker = new Worker;
+        worker->moveToThread(&workerThread);
+        connect(workerThread, &QThread::finished, worker, &QObject::deleteLater);
+        connect(this, &Controller::operate, worker, &Worker::doWork);
+        connect(worker, &Worker::resultReady, this, &Controller::handleResults);
+        workerThread.start();
+    }
+    ~Controller() {
+        workerThread.quit();
+        workerThread.wait();
+    }
+public slots:
+    void handleResults(const QString &);
+signals:
+    void operate(const QString &);
 };
-//! [1]
+//! [worker]