From a15bc0e714539c3dca8476254780e645bbbe1a12 Mon Sep 17 00:00:00 2001 From: Sze Howe Koh Date: Wed, 2 Oct 2013 22:31:05 +0800 Subject: Doc: Show both low- and high-level thread syncing on the same page Move text from "Thread Basics" to "Synchronizing Threads" for a more complete overview. Change-Id: Ib87259ed551fa77278b57c5922df7f4b774a829a Reviewed-by: Olivier Goffart Reviewed-by: Jerome Pasion --- src/corelib/doc/src/threads-basics.qdoc | 23 ----------------------- src/corelib/doc/src/threads.qdoc | 31 +++++++++++++++++++++++++++++-- 2 files changed, 29 insertions(+), 25 deletions(-) (limited to 'src/corelib/doc/src') diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc index 9cf93d40fd..5d6e0f6ef1 100644 --- a/src/corelib/doc/src/threads-basics.qdoc +++ b/src/corelib/doc/src/threads-basics.qdoc @@ -275,29 +275,6 @@ operation. One disadvantage is that external mutexes aid locking, but do not enforce it because users of the object may forget to use it. - \section2 Using the Event Loop to Prevent Data Corruption - - Qt's \l{The Event System}{event system} is very useful for inter-thread - communication. Every thread may have its own event loop. To call a slot (or - any \l{Q_INVOKABLE}{invokable} method) in another thread, place that call in - the target thread's event loop. This lets the target thread finish its current - task before the slot starts running, while the original thread continues - running in parallel. - - To place an invocation in an event loop, make a queued \l{Signals & Slots} - {signal-slot} connection. Whenever the signal is emitted, its arguments will - be recorded by the event system. The thread that the signal receiver - \l{QObject#Thread Affinity}{lives in} will then run the slot. Alternatively, - call QMetaObject::invokeMethod() to achieve the same effect without signals. - In both cases, a \l{Qt::QueuedConnection}{queued connection} must be used - because a \l{Qt::DirectConnection}{direct connection} bypasses the event - system and runs the method immediately in the current thread. - - There is no risk of deadlocks when using the event system for thread - synchronization, unlike using low-level primitives. - - \sa QThread::exec(), {Threads and QObjects} - \section2 Dealing with Asynchronous Execution One way to obtain a worker thread's result is by waiting for the thread diff --git a/src/corelib/doc/src/threads.qdoc b/src/corelib/doc/src/threads.qdoc index c250f7466b..d8592bbf09 100644 --- a/src/corelib/doc/src/threads.qdoc +++ b/src/corelib/doc/src/threads.qdoc @@ -290,14 +290,18 @@ \contentspage Thread Support in Qt \nextpage Reentrancy and Thread-Safety - The QMutex, QReadWriteLock, QSemaphore, and QWaitCondition - classes provide means to synchronize threads. While the main idea + While the main idea with threads is that they should be as concurrent as possible, there are points where threads must stop and wait for other threads. For example, if two threads try to access the same global variable simultaneously, the results are usually undefined. + Qt provides low-level primitives as well as high-level mechanisms + for synchronizing threads. + + \section1 Low-Level Synchronization Primitives + QMutex provides a mutually exclusive lock, or mutex. At most one thread can hold the mutex at any time. If a thread tries to acquire the mutex while the mutex is already locked, the thread will @@ -333,6 +337,29 @@ Note that Qt's synchronization classes rely on the use of properly aligned pointers. For instance, you cannot use packed classes with MSVC. + + \section1 High-Level Event Queues + + Qt's \l{The Event System}{event system} is very useful for inter-thread + communication. Every thread may have its own event loop. To call a slot (or + any \l{Q_INVOKABLE}{invokable} method) in another thread, place that call in + the target thread's event loop. This lets the target thread finish its current + task before the slot starts running, while the original thread continues + running in parallel. + + To place an invocation in an event loop, make a queued \l{Signals & Slots} + {signal-slot} connection. Whenever the signal is emitted, its arguments will + be recorded by the event system. The thread that the signal receiver + \l{QObject#Thread Affinity}{lives in} will then run the slot. Alternatively, + call QMetaObject::invokeMethod() to achieve the same effect without signals. + In both cases, a \l{Qt::QueuedConnection}{queued connection} must be used + because a \l{Qt::DirectConnection}{direct connection} bypasses the event + system and runs the method immediately in the current thread. + + There is no risk of deadlocks when using the event system for thread + synchronization, unlike using low-level primitives. + + \sa QThread::exec(), {Threads and QObjects} */ /*! -- cgit v1.2.3