diff options
author | Sze Howe Koh <szehowe.koh@gmail.com> | 2013-10-02 22:26:47 +0800 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2013-10-06 01:08:01 +0200 |
commit | 525712b75e4f7a49a09b5e3d88b6000d722a33d7 (patch) | |
tree | dd8669b4aac7f1ab9725f3093b5c088b280f9e98 /src/corelib/doc | |
parent | 3b45dfe6e6ff6c0626bc693599725ced639a40aa (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.qdoc | 40 |
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 |