summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc
diff options
context:
space:
mode:
authorSze Howe Koh <szehowe.koh@gmail.com>2013-10-02 22:26:47 +0800
committerThe Qt Project <gerrit-noreply@qt-project.org>2013-10-06 01:08:01 +0200
commit525712b75e4f7a49a09b5e3d88b6000d722a33d7 (patch)
treedd8669b4aac7f1ab9725f3093b5c088b280f9e98 /src/corelib/doc
parent3b45dfe6e6ff6c0626bc693599725ced639a40aa (diff)
Doc: Rewrite section on threaded event loops
- Focus on signals instead of events; programs rarely need to call QCoreApplication::postEvent() manually - Mention QMetaMethod::invokeMethod() - Reduce verbosity Change-Id: I170b96bd0134c0bc102ef1a344d4f0b88e504f86 Reviewed-by: Olivier Goffart <ogoffart@woboq.com> Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Diffstat (limited to 'src/corelib/doc')
-rw-r--r--src/corelib/doc/src/threads-basics.qdoc40
1 files changed, 20 insertions, 20 deletions
diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc
index 67165b0c24..9cf93d40fd 100644
--- a/src/corelib/doc/src/threads-basics.qdoc
+++ b/src/corelib/doc/src/threads-basics.qdoc
@@ -277,26 +277,26 @@
\section2 Using the Event Loop to Prevent Data Corruption
- The event loops of Qt are a very valuable tool for inter-thread
- communication. Every thread may have its own event loop. A safe way of
- calling a slot in another thread is by placing that call in another
- thread's event loop. This ensures that the target object finishes the
- method that is currently running before another method is started.
-
- So how is it possible to put a method invocation in an event loop? Qt has
- two ways of doing this. One way is via queued signal-slot connections; the
- other way is to post an event with QCoreApplication::postEvent(). A queued
- signal-slot connection is a signal slot connection that is executed
- asynchronously. The internal implementation is based on posted events. The
- arguments of the signal are put into the event loop and the signal method
- returns immediately.
-
- The connected slot will be executed at a time which depends on what else is
- in the event loop.
-
- Communication via the event loop eliminates the deadlock problem we face
- when using mutexes. This is why we recommend using the event loop rather
- than locking an object using a mutex.
+ 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