summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSze Howe Koh <szehowe.koh@gmail.com>2014-02-25 08:23:48 (GMT)
committerThe Qt Project <gerrit-noreply@qt-project.org>2014-03-13 16:17:35 (GMT)
commitdd03e7db8f47fb79bd9120fb03e118fa86668cd3 (patch)
tree78ab507fcdbc7bb6a0443298c2a95e64ee27a258
parent28984cd5ba63c557b88377f996a90b9665f37745 (diff)
downloadQt-dd03e7db8f47fb79bd9120fb03e118fa86668cd3.zip
Qt-dd03e7db8f47fb79bd9120fb03e118fa86668cd3.tar.gz
Qt-dd03e7db8f47fb79bd9120fb03e118fa86668cd3.tar.bz2
Doc: Update, and reduce duplication of, QThread-related info
Added/Changed: - Move content from the Thread Basics overview to the QThread class ref - Rephrase bits for clarity - Use more links Removed: - (threads-basics.qdoc) Warning against moveToThread(this): This usage came about when people tried to add slots to a QThread subclass. This patch adds a warning against the root cause. - (threads-basics.qdoc) The strategy for managing member variables: Sounds error-prone. Pushing results through signals is safer. - (qthread.cpp) The note about GUI classes: Irrelevant to QThread, and it's already mentioned elsewhere. This is a cherry-pick from a9d5627e6a7b82 in qtbase.git. Change-Id: I491f64f998050daf0251abb2126bc9f7a198c17d Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com> Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
-rw-r--r--doc/src/tutorials/threads.qdoc25
-rw-r--r--src/corelib/thread/qthread.cpp29
2 files changed, 15 insertions, 39 deletions
diff --git a/doc/src/tutorials/threads.qdoc b/doc/src/tutorials/threads.qdoc
index ad66b9f..18e0cdc 100644
--- a/doc/src/tutorials/threads.qdoc
+++ b/doc/src/tutorials/threads.qdoc
@@ -291,31 +291,6 @@
still important.
On Linux, Valgrind and Helgrind can help detect threading errors.
- The anatomy of QThread is quite interesting:
-
- \list
- \o QThread does not live in the new thread where \l{QThread::}{run()} is
- executed. It lives in the old thread.
- \o Most QThread methods are the thread's control interface and are meant to
- be called from the old thread. Do not move this interface to the newly
- created thread using \l{QObject::}{moveToThread()}; i.e., calling
- \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
- practice.
- \o \l{QThread::}{exec()} and the static methods
- \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
- \l{QThread::}{sleep()} are meant to be called from the newly created
- thread.
- \o Additional members defined in the QThread subclass are
- accessible by both threads. The developer is responsible for
- coordinating access. A typical strategy is to set the members before
- \l{QThread::}{start()} is called. Once the worker thread is running,
- the main thread should not touch the additional members anymore. After
- the worker has terminated, the main thread can access the additional
- members again. This is a convenient strategy for passing parameters to a
- thread before it is started as well as for collecting the result once it
- has terminated.
- \endlist
-
\section2 Using a Mutex to Protect the Integrity of Data
A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp
index 9c7060d..4dc28f8 100644
--- a/src/corelib/thread/qthread.cpp
+++ b/src/corelib/thread/qthread.cpp
@@ -228,20 +228,20 @@ QThreadPrivate::~QThreadPrivate()
There will not be any event loop running in the thread unless you call
exec().
- It is important to remember that a QThread object usually lives
- in the thread where it was created, not in the thread that it
- manages. This oft-overlooked detail means that a QThread's slots
- will be executed in the context of its home thread, not in the
- context of the thread it is managing. For this reason,
- implementing new slots in a QThread subclass is error-prone and
- discouraged.
+ It is important to remember that a QThread instance \l{QObject#Thread
+ Affinity}{lives in} the old thread that instantiated it, not in the
+ new thread that calls run(). This means that all of QThread's queued
+ slots will execute in the old thread. Thus, a developer who wishes to
+ invoke slots in the new thread must use the worker-object approach; new
+ slots should not be implemented directly into a subclassed QThread.
- \note If you interact with an object, using any technique other
- than queued signal/slot connections (e.g. direct function calls),
- then the usual multithreading precautions need to be taken.
+ When subclassing QThread, keep in mind that the constructor executes in
+ the old thread while run() executes in the new thread. If a member
+ variable is accessed from both functions, then the variable is accessed
+ from two different threads. Check that it is safe to do so.
- \note It is not possible to change the thread affinity of GUI
- objects; they must remain in the main thread.
+ \note Care must be taken when interacting with objects across different
+ threads. See \l{Synchronizing Threads} for details.
\section1 Managing threads
@@ -286,7 +286,7 @@ QThreadPrivate::~QThreadPrivate()
wait(), consider listening for the finished() signal. Instead of
the sleep() functions, consider using QTimer.
- \sa {Thread Support in Qt}, QThreadStorage, QMutex, QSemaphore, QWaitCondition,
+ \sa {Thread Support in Qt}, QThreadStorage, {Synchronizing Threads}
{Mandelbrot Example}, {Semaphores Example}, {Wait Conditions Example}
*/
@@ -518,7 +518,8 @@ uint QThread::stackSize() const
that was passed to exit(). The value returned is 0 if exit() is called via
quit().
- It is necessary to call this function to start event handling.
+ This function is meant to be called from within run(). It is necessary to
+ call this function to start event handling.
\sa quit(), exit()
*/