diff options
author | Sze Howe Koh <szehowe.koh@gmail.com> | 2013-10-16 23:37:28 +0800 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2013-10-21 02:12:11 +0200 |
commit | a9d5627e6a7b82188e20064d2e397b00cff8f318 (patch) | |
tree | c5cda04a4d3f77f671e02cc5db582da0dbf32599 /src/corelib/thread/qthread.cpp | |
parent | da7e534df254b4b03c289d4286f887cd98059782 (diff) |
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 <geir.vattekar@digia.com>
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>
Diffstat (limited to 'src/corelib/thread/qthread.cpp')
-rw-r--r-- | src/corelib/thread/qthread.cpp | 29 |
1 files changed, 15 insertions, 14 deletions
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() */ |