From 013793a78341f7f2ea7e3a25caa4b50e646d74bb Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Wed, 26 Mar 2025 19:44:03 -0700 Subject: [PATCH] QThread/Doc: improve docs on running, finished, and the OS thread And take the opportunity to explain that the finished() signal does not indicate the end of the operating system thread. Indeed, on some OSes, not even wait() can be sure of that: for Unix systems, see the docs at the top of qthread_unix.cpp about timed pthread_joins. Pick-to: 6.8 Fixes: QTBUG-135163 Change-Id: Ie00a742f0707f57c767bfffd44bdaec40df05e4a Reviewed-by: Fabian Kosmale Reviewed-by: Andreas Eliasson (cherry picked from commit de90f2e064ffef2ed751b7805d81a93668dc67a2) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/thread/qthread.cpp | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp index b5b4618e0bd..571fc015bb6 100644 --- a/src/corelib/thread/qthread.cpp +++ b/src/corelib/thread/qthread.cpp @@ -470,6 +470,16 @@ QThread::~QThread() \threadsafe Returns \c true if the thread is finished; otherwise returns \c false. + A thread is considered finished if it has returned from the run() function + and the finished() signal has been emitted. + +//! [execution-after-finished] + Note the thread may still run for arbitrary amount of time after the + finished() signal is emitted, running clean-up operations such as executing + the destructors to \c{thread_local} variables. To synchronize with all + effects from the thread, call wait() and verify it returned true. +//! [execution-after-finished] + \sa isRunning() */ bool QThread::isFinished() const @@ -483,6 +493,11 @@ bool QThread::isFinished() const \threadsafe Returns \c true if the thread is running; otherwise returns \c false. + A thread is considered to be running if QThread has been started with + start() but is not yet finished. + + \include qthread.cpp execution-after-finished + \sa isFinished() */ bool QThread::isRunning() const @@ -924,6 +939,12 @@ QThread::Priority QThread::priority() const This provides similar functionality to the POSIX \c pthread_join() function. + \note On some operating systems, this function may return true while the + operating system thread is still running and may be executing clean-up code + such as C++11 \c{thread_local} destructors. Operating systems where this + function only returns true after the OS thread has fully exited include + Linux, Windows, and Apple operating systems. + \sa sleep(), terminate() */ bool QThread::wait(QDeadlineTimer deadline)