diff options
| author | Thiago Macieira <thiago.macieira@intel.com> | 2025-03-26 19:44:03 -0700 |
|---|---|---|
| committer | Thiago Macieira <thiago.macieira@intel.com> | 2025-03-29 11:50:23 -0700 |
| commit | de90f2e064ffef2ed751b7805d81a93668dc67a2 (patch) | |
| tree | a2ce3d2665f42dc00cc337826d790003f67a8638 /src/corelib/thread/qthread.cpp | |
| parent | 771466b9e7c62086f7554974cc7658cefe38d2e7 (diff) | |
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.9 6.8
Fixes: QTBUG-135163
Change-Id: Ie00a742f0707f57c767bfffd44bdaec40df05e4a
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
Diffstat (limited to 'src/corelib/thread/qthread.cpp')
| -rw-r--r-- | src/corelib/thread/qthread.cpp | 21 |
1 files changed, 21 insertions, 0 deletions
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) |