From a9d5627e6a7b82188e20064d2e397b00cff8f318 Mon Sep 17 00:00:00 2001 From: Sze Howe Koh Date: Wed, 16 Oct 2013 23:37:28 +0800 Subject: 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) Note on sleep() et al.: They were made public in Qt 5.0. - (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. Change-Id: I6bc53cc22b929523f9976d2b920f94c02bd7273e Reviewed-by: Geir Vattekar Reviewed-by: Olivier Goffart --- src/corelib/doc/src/threads-basics.qdoc | 25 ------------------------- src/corelib/thread/qthread.cpp | 29 +++++++++++++++-------------- 2 files changed, 15 insertions(+), 39 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc index e511c10423..4f381421b4 100644 --- a/src/corelib/doc/src/threads-basics.qdoc +++ b/src/corelib/doc/src/threads-basics.qdoc @@ -199,31 +199,6 @@ still important. On Linux, Valgrind and Helgrind can help detect threading errors. - The anatomy of QThread is quite interesting: - - \list - \li QThread does not live in the new thread where \l{QThread::}{run()} is - executed. It lives in the old thread. - \li 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. - \li \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. - \li 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 Protecting the Integrity of Data When writing a multithread application, extra care must be taken to avoid diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp index 7667aff0b2..50ccca9eda 100644 --- a/src/corelib/thread/qthread.cpp +++ b/src/corelib/thread/qthread.cpp @@ -204,20 +204,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 @@ -262,7 +262,7 @@ QThreadPrivate::~QThreadPrivate() \l{Mandelbrot Example}, as that is the name of the QThread subclass). Note that this is currently not available with release builds on Windows. - \sa {Thread Support in Qt}, QThreadStorage, QMutex, QSemaphore, QWaitCondition, + \sa {Thread Support in Qt}, QThreadStorage, {Synchronizing Threads} {Mandelbrot Example}, {Semaphores Example}, {Wait Conditions Example} */ @@ -489,7 +489,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() */ -- cgit v1.2.3