Remove the QThread::terminated() signal

The signal is removed from the API; all references to it are removed
from documentation; the unit test that checks for its emission is
modified to listen for QThread::finished() instead.

The QThreadPrivate::terminated flag is also removed, as it served no
purpose other than to trigger the emission of QThread::terminated()

As discussed at http://lists.qt-project.org/pipermail/development/2012-October/007216.html
the signal is not guaranteed to be emitted after every termination,
rendering it useless.

Change-Id: I7b0c45d7889da0d33875545331606f2208ee56fc
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>

dist/changes-5.0.0

@@ -323,6 +323,8 @@ information about a particular change.
 
 - QAbstractPageSetupDialog has been removed.
 
+- QThread::terminated() has been removed, since its emission cannot be guaranteed.
+
 ****************************************************************************
 *                           General                                        *
 ****************************************************************************

src/corelib/thread/qthread.cpp

@@ -144,7 +144,7 @@ void QAdoptedThread::run()
 */
 
 QThreadPrivate::QThreadPrivate(QThreadData *d)
-    : QObjectPrivate(), running(false), finished(false), terminated(false),
+    : QObjectPrivate(), running(false), finished(false),
       isInFinish(false), exited(false), returnCode(-1),
       stackSize(0), priority(QThread::InheritPriority), data(d)
 {
@@ -203,10 +203,9 @@ QThreadPrivate::~QThreadPrivate()
 
     \section1 Managing threads
 
-    QThread will notifiy you via a signal
+    QThread will notifiy you via a signal when the thread is
-    when the thread is started(), finished(), and terminated(), or
+    started() and finished(), or you can use isFinished() and
-    you can use isFinished() and isRunning() to query the state of
+    isRunning() to query the state of the thread.
-    the thread.
 
     You can stop the thread by calling exit() or quit(). In extreme
     cases, you may want to forcibly terminate() an executing thread.
@@ -326,7 +325,7 @@ QThreadPrivate::~QThreadPrivate()
     This signal is emitted from the associated thread when it starts executing,
     before the run() function is called.
 
-    \sa finished(), terminated()
+    \sa finished()
 */
 
 /*!
@@ -341,17 +340,7 @@ QThreadPrivate::~QThreadPrivate()
     \note If the associated thread was terminated using terminate(), it is undefined from
     which thread this signal is emitted.
 
-    \sa started(), terminated()
+    \sa started()
-*/
-
-/*!
-    \fn void QThread::terminated()
-
-    This signal is emitted when the thread is terminated.
-
-    It is undefined from which thread this signal is emitted.
-
-    \sa started(), finished()
 */
 
 /*!
@@ -656,8 +645,8 @@ QThread::Priority QThread::priority() const
 
     Terminates the execution of the thread. The thread may or may not
     be terminated immediately, depending on the operating system's
-    scheduling policies. Listen for the terminated() signal, or use
+    scheduling policies. Use QThread::wait() after terminate(), to be
-    QThread::wait() after terminate(), to be sure.
+    sure.
 
     When the thread is terminated, all threads waiting for the thread
     to finish will be woken up.

src/corelib/thread/qthread.h

@@ -113,7 +113,6 @@ public:
 Q_SIGNALS:
     void started();
     void finished();
-    void terminated();
 
 protected:
     virtual void run();

src/corelib/thread/qthread_p.h

@@ -147,7 +147,6 @@ public:
 
     bool running;
     bool finished;
-    bool terminated;
     bool isInFinish; //when in QThreadPrivate::finish
 
     bool exited;

src/corelib/thread/qthread_unix.cpp

@@ -346,16 +346,12 @@ void QThreadPrivate::finish(void *arg)
 
     d->isInFinish = true;
     d->priority = QThread::InheritPriority;
-    bool terminated = d->terminated;
     void *data = &d->data->tls;
     locker.unlock();
-    if (terminated)
-        emit thr->terminated();
     emit thr->finished();
     QCoreApplication::sendPostedEvents(0, QEvent::DeferredDelete);
     QThreadStorageData::finish((void **)data);
     locker.relock();
-    d->terminated = false;
 
     QAbstractEventDispatcher *eventDispatcher = d->data->eventDispatcher;
     if (eventDispatcher) {
@@ -523,7 +519,6 @@ void QThread::start(Priority priority)
 
     d->running = true;
     d->finished = false;
-    d->terminated = false;
     d->returnCode = 0;
     d->exited = false;
 
@@ -631,8 +626,6 @@ void QThread::terminate()
     if (code) {
         qWarning("QThread::start: Thread termination error: %s",
                  qPrintable(qt_error_string((code))));
-    } else {
-        d->terminated = true;
     }
 #endif
 }

src/corelib/thread/qthread_win.cpp

@@ -352,18 +352,13 @@ void QThreadPrivate::finish(void *arg, bool lockAnyway)
     QMutexLocker locker(lockAnyway ? &d->mutex : 0);
     d->isInFinish = true;
     d->priority = QThread::InheritPriority;
-    bool terminated = d->terminated;
     void **tls_data = reinterpret_cast<void **>(&d->data->tls);
     locker.unlock();
-    if (terminated)
-        emit thr->terminated();
     emit thr->finished();
     QCoreApplication::sendPostedEvents(0, QEvent::DeferredDelete);
     QThreadStorageData::finish(tls_data);
     locker.relock();
 
-    d->terminated = false;
-
     QAbstractEventDispatcher *eventDispatcher = d->data->eventDispatcher;
     if (eventDispatcher) {
         d->data->eventDispatcher = 0;
@@ -443,7 +438,6 @@ void QThread::start(Priority priority)
 
     d->running = true;
     d->finished = false;
-    d->terminated = false;
     d->exited = false;
     d->returnCode = 0;
 
@@ -524,7 +518,6 @@ void QThread::terminate()
         return;
     }
     TerminateThread(d->handle, 0);
-    d->terminated = true;
     QThreadPrivate::finish(this, false);
 }
 
@@ -562,7 +555,7 @@ bool QThread::wait(unsigned long time)
 
     if (ret && !d->finished) {
         // thread was terminated by someone else
-        d->terminated = true;
+
         QThreadPrivate::finish(this, false);
     }
 
@@ -583,7 +576,6 @@ void QThread::setTerminationEnabled(bool enabled)
     QMutexLocker locker(&d->mutex);
     d->terminationEnabled = enabled;
     if (enabled && d->terminatePending) {
-        d->terminated = true;
         QThreadPrivate::finish(thr, false);
         locker.unlock(); // don't leave the mutex locked!
         _endthreadex(0);

tests/auto/corelib/thread/qthread/tst_qthread.cpp

@@ -77,7 +77,7 @@ private slots:
     void quit();
     void started();
     void finished();
-    void terminated();
+    void terminated(); // Named after a signal that was removed in Qt 5.0
     void exec();
     void sleep();
     void msleep();
@@ -535,7 +535,7 @@ void tst_QThread::terminated()
 {
     SignalRecorder recorder;
     Terminate_Thread thread;
-    connect(&thread, SIGNAL(terminated()), &recorder, SLOT(slot()), Qt::DirectConnection);
+    connect(&thread, SIGNAL(finished()), &recorder, SLOT(slot()), Qt::DirectConnection);
     {
         QMutexLocker locker(&thread.mutex);
         thread.start();