1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\group thread
\title Threading Classes
These \l{Qt Core} classes provide threading support to applications.
The \l{Thread Support in Qt} page covers how to use these classes.
*/
/*!
\page threads.html
\title Thread Support in Qt
\ingroup qt-basic-concepts
\brief A detailed discussion of thread handling in Qt.
\ingroup frameworks-technologies
\nextpage Multithreading Technologies in Qt
Qt provides thread support in the form of platform-independent
threading classes, a thread-safe way of posting events, and
signal-slot connections across threads. This makes it easy to
develop portable multithreaded Qt applications and take advantage
of multiprocessor machines. Multithreaded programming is also a
useful paradigm for performing time-consuming operations without
freezing the user interface of an application.
Earlier versions of Qt offered an option to build the library
without thread support. Since Qt 4.0, threads are always enabled.
\section1 Topics:
\list
\li \l{Recommended Reading}
\li \l{The Threading Classes}
\li \l{Multithreading Technologies in Qt}
\li \l{Synchronizing Threads}
\li \l{Reentrancy and Thread-Safety}
\li \l{Threads and QObjects}
\li \l{Thread-Support in Qt Modules}
\endlist
\section1 Recommended Reading
This document is intended for an audience that has knowledge of,
and experience with, multithreaded applications. If you are new
to threading see our Recommended Reading list:
\list
\li \l {http://www.amazon.com/Threads-Primer-Guide-Multithreaded-Programming/dp/0134436989}{Threads Primer: A Guide to Multithreaded Programming}
\li \l {http://www.amazon.com/Thread-Time-MultiThreaded-Programming-Guide/dp/0131900676}{Thread Time: The Multithreaded Programming Guide}
\li \l {http://www.amazon.com/Pthreads-Programming-Standard-Multiprocessing-Nutshell/dp/1565921151a}{Pthreads Programming: A POSIX Standard for Better Multiprocessing}
\li \l {http://www.amazon.com/WIN32-Multithreaded-Programming-Aaron-Cohen/dp/1565922964}{Win32 Multithreaded Programming}
\endlist
\section1 The Threading Classes
These classes are relevant to threaded applications.
\annotatedlist thread
\omit
\list
\li QThread provides the means to start a new thread.
\li QThreadStorage provides per-thread data storage.
\li QThreadPool manages a pool of threads that run QRunnable objects.
\li QRunnable is an abstract class representing a runnable object.
\li QMutex provides a mutual exclusion lock, or mutex.
\li QMutexLocker is a convenience class that automatically locks
and unlocks a QMutex.
\li QReadWriteLock provides a lock that allows simultaneous read access.
\li QReadLocker and QWriteLocker are convenience classes that automatically
lock and unlock a QReadWriteLock.
\li QSemaphore provides an integer semaphore (a generalization of a mutex).
\li QWaitCondition provides a way for threads to go to sleep until
woken up by another thread.
\li QAtomicInt provides atomic operations on integers.
\li QAtomicPointer provides atomic operations on pointers.
\endlist
\endomit
\note Qt's threading classes are implemented with native threading APIs;
e.g., Win32 and pthreads. Therefore, they can be used with threads of the
same native API.
*/
/*!
\page threads-technologies.html
\title Multithreading Technologies in Qt
\ingroup qt-basic-concepts
\brief An overview and comparison of different ways to use threads in Qt.
\ingroup frameworks-technologies
\contentspage Thread Support in Qt
\previouspage Thread Support in Qt
\nextpage Synchronizing Threads
Qt offers many classes and functions for working with threads. Below are
four different approaches that Qt programmers can use to implement
multithreaded applications.
\section1 QThread: Low-Level API with Optional Event Loops
QThread is the foundation of all thread control in Qt. Each QThread
instance represents and controls one thread.
QThread can either be instantiated directly or subclassed. Instantiating a
QThread provides a parallel event loop, allowing QObject slots to be invoked
in a secondary thread. Subclassing a QThread allows the application to initialize
the new thread before starting its event loop, or to run parallel code
without an event loop.
See the \l{QThread}{QThread class reference} and the \l{Threading and
Concurrent Programming Examples}{threading examples} for demonstrations on
how to use QThread.
\section1 QThreadPool and QRunnable: Reusing Threads
Creating and destroying threads frequently can be expensive. To reduce this
overhead, existing threads can be reused for new tasks. QThreadPool is a
collection of reuseable QThreads.
To run code in one of a QThreadPool's threads, reimplement QRunnable::run()
and instantiate the subclassed QRunnable. Use QThreadPool::start() to put
the QRunnable in the QThreadPool's run queue. When a thread becomes available,
the code within QRunnable::run() will execute in that thread.
Each Qt application has a global thread pool, which is accessible through
QThreadPool::globalInstance(). This global thread pool automatically maintains
an optimal number of threads based on the number of cores in the CPU. However,
a separate QThreadPool can be created and managed explicitly.
\section1 Qt Concurrent: Using a High-level API
The \l{Qt Concurrent} module provides high-level functions that deal with some
common parallel computation patterns: map, filter, and reduce. Unlike using
QThread and QRunnable, these functions never require the use of \l{Synchronizing
Threads#Low-Level Synchronization Primitives}{low-level threading primitives}
such as mutexes or semaphores. Instead, they return a QFuture object which can
be used to retrieve the functions' results when they are ready. QFuture can
also be used to query computation progress and to pause/resume/cancel the
computation. For convenience, QFutureWatcher enables interactions with
\l{QFuture}s via signals and slots.
\l{Qt Concurrent}'s map, filter and reduce algorithms automatically distribute
computation across all available processor cores, so applications written today
will continue to scale when deployed later on a system with more cores.
This module also provides the QtConcurrent::run() function, which can run any
function in another thread. However, QtConcurrent::run() only supports a subset
of features available to the map, filter and reduce functions. The QFuture
can be used to retrieve the function's return value and to check if the thread
is running. However, a call to QtConcurrent::run() uses one thread only, cannot
be paused/resumed/canceled, and cannot be queried for progress.
See the \l{Qt Concurrent} module documentation for details on the individual functions.
\section1 WorkerScript: Threading in QML
The WorkerScript QML type lets JavaScript code run in parallel with the GUI
thread.
Each WorkerScript instance can have one \c{.js} script attached to it. When
WorkerScript::sendMessage() is called, the script will run in a separate thread
(and a separate \l{QQmlContext}{QML context}). When the script finishes
running, it can send a reply back to the GUI thread which will invoke the
WorkerScript::onMessage() signal handler.
Using a WorkerScript is similar to using a worker QObject that has been moved
to another thread. Data is transferred between threads via signals.
See the WorkerScript documentation for details on how to implement the script,
and for a list of data types that can be passed between threads.
\section1 Choosing an Appropriate Approach
As demonstrated above, Qt provides different solutions for developing threaded
applications. The right solution for a given application depends on the purpose
of the new thread and the thread's lifetime. Below is a comparison of Qt's
threading technologies, followed by recommended solutions for some example use cases.
\section2 Comparison of Solutions
\table
\header
\li Feature
\li QThread
\li QRunnable and QThreadPool
\li QtConcurrent::run()
\li Qt Concurrent (Map, Filter, Reduce)
\li WorkerScript
\row
\li API
\li C++
\li C++
\li C++
\li C++
\li QML
\row
\li Thread priority can be specified
\li Yes
\li Yes
\li
\li
\li
\row
\li Thread can run an event loop
\li Yes
\li
\li
\li
\li
\row
\li Thread can receive data updates through signals
\li Yes (received by a worker QObject)
\li
\li
\li
\li Yes (received by WorkerScript)
\row
\li Thread can be controlled using signals
\li Yes (received by QThread)
\li
\li
\li Yes (received by QFutureWatcher)
\li
\row
\li Thread can be monitored through a QFuture
\li
\li
\li Partially
\li Yes
\li
\row
\li Built-in ability to pause/resume/cancel
\li
\li
\li
\li Yes
\li
\endtable
\section2 Example Use Cases
\table
\header
\li Lifetime of thread
\li Operation
\li Solution
\row
\li One call
\li Run a new linear function within another thread, optionally with progress
updates during the run.
\li Qt provides different solutions:
\list
\li Place the function in a reimplementation of QThread::run() and
start the QThread. Emit signals to update progress. OR
\li Place the function in a reimplementation of QRunnable::run() and
add the QRunnable to a QThreadPool. Write to a \l{Synchronizing
Threads}{thread-safe variable} to update progress. OR
\li Run the function using QtConcurrent::run(). Write to a \l{Synchronizing
Threads}{thread-safe variable} to update progress.
\endlist
\row
\li One call
\li Run an existing function within another thread and get its return value.
\li Run the function using QtConcurrent::run(). Have a QFutureWatcher emit
the \l{QFutureWatcher::}{finished()} signal when the function has
returned, and call QFutureWatcher::result() to get the function's return
value.
\row
\li One call
\li Perform an operation on all items of a container, using all available
cores. For example, producing thumbnails from a list of images.
\li Use Qt Concurrent's \l{QtConcurrent::}{filter()} function to select
container elements, and the \l{QtConcurrent::}{map()} function to apply
an operation to each element. To fold the output into a single result,
use \l{QtConcurrent::}{filteredReduced()} and
\l{QtConcurrent::}{mappedReduced()} instead.
\row
\li One call/Permanent
\li Perfrom a long computation in a pure QML application, and update the GUI
when the results are ready.
\li Place the computation code in a \c{.js} script and attach it to a
WorkerScript instance. Call \l{WorkerScript::}{sendMessage()} to start the
computation in a new thread. Let the script call WorkerScript::sendMessage()
too, to pass the result back to the GUI thread. Handle the result in
\l{WorkerScript::}{onMessage} and update the GUI there.
\row
\li Permanent
\li Have an object living in another thread that can perform different
tasks upon request and/or can receive new data to work with.
\li Subclass a QObject to create a worker. Instantiate this worker object
and a QThread. Move the worker to the new thread. Send commands or
data to the worker object over queued signal-slot connections.
\row
\li Permanent
\li Repeatedly perform an expensive operation in another thread, where the
thread does not need to receive any signals or events.
\li Write the infinite loop directly within a reimplementation of QThread::run().
Start the thread without an event loop. Let the thread emit signals to
send data back to the GUI thread.
\endtable
*/
/*!
\page threads-synchronizing.html
\title Synchronizing Threads
\previouspage Multithreading Technologies in Qt
\contentspage Thread Support in Qt
\nextpage Reentrancy and Thread-Safety
While the purpose of threads is to allow code to run in parallel,
there are times where threads must stop and wait for other
threads. For example, if two threads try to write to the same
variable simultaneously, the result is undefined. The principle of
forcing threads to wait for one another is called \e{mutual exclusion}.
It is a common technique for protecting shared resources such as data.
Qt provides low-level primitives as well as high-level mechanisms
for synchronizing threads.
\section1 Low-Level Synchronization Primitives
QMutex is the basic class for enforcing mutual exclusion. A thread
locks a mutex in order to gain access to a shared resource. If a second
thread tries to lock the mutex while it is already locked, the second
thread will be put to sleep until the first thread completes its task
and unlocks the mutex.
QReadWriteLock is similar to QMutex, except that it distinguishes
between "read" and "write" access. When a piece of data is not being
written to, it is safe for multiple threads to read from it simultaneously.
A QMutex forces multiple readers to take turns to read shared data, but a
QReadWriteLock allows simultaneous reading, thus improving parallelism.
QSemaphore is a generalization of QMutex that protects a certain
number of identical resources. In contrast, a QMutex protects
exactly one resource. The \l{Semaphores Example} shows a typical application
of semaphores: synchronizing access to a circular buffer between a producer
and a consumer.
QWaitCondition synchronizes threads not by enforcing mutual exclusion but by
providing a \e{condition variable}. While the other primitives make threads
wait until a resource is unlocked, QWaitCondition makes threads wait until a
particular condition has been met. To allow the waiting threads to proceed,
call \l{QWaitCondition::wakeOne()}{wakeOne()} to wake one randomly
selected thread or \l{QWaitCondition::wakeAll()}{wakeAll()} to wake them all
simultaneously. The \l{Wait Conditions Example} shows how to solve the
producer-consumer problem using QWaitCondition instead of QSemaphore.
\note Qt's synchronization classes rely on the use of properly
aligned pointers. For instance, you cannot use packed classes with
MSVC.
These synchronization classes can be used to make a method thread safe.
However, doing so incurs a performance penalty, which is why most Qt methods
are not made thread safe.
\section2 Risks
If a thread locks a resource but does not unlock it, the application may
freeze because the resource will become permanently unavailable to other threads.
This can happen, for example, if an exception is thrown and forces the current
function to return without releasing its lock.
Another similar scenario is a \e{deadlock}. For example, suppose that
thread A is waiting for thread B to unlock a resource. If thread B is also
waiting for thread A to unlock a different resource, then both threads will
end up waiting forever, so the application will freeze.
\section2 Convenience classes
QMutexLocker, QReadLocker and QWriteLocker are convenience classes that make it
easier to use QMutex and QReadWriteLock. They lock a resource when they are
constructed, and automatically unlock it when they are destroyed. They are
designed to simplify code that use QMutex and QReadWriteLock, thus reducing
the chances that a resource becomes permanently locked by accident.
\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. However, the event system
does not enforce mutual exclusion. If invokable methods access shared data,
they must still be protected with low-level primitives.
Having said that, Qt's event system, along with \l{Implicit Sharing}{implicitly
shared} data structures, offers an alternative to traditional thread locking.
If signals and slots are used exclusively and no variables are shared between
threads, a multithreaded program can do without low-level primitives altogether.
\sa QThread::exec(), {Threads and QObjects}
*/
/*!
\page threads-reentrancy.html
\title Reentrancy and Thread-Safety
\keyword reentrant
\keyword thread-safe
\previouspage Synchronizing Threads
\contentspage Thread Support in Qt
\nextpage Threads and QObjects
Throughout the documentation, the terms \e{reentrant} and
\e{thread-safe} are used to mark classes and functions to indicate
how they can be used in multithread applications:
\list
\li A \e thread-safe function can be called simultaneously from
multiple threads, even when the invocations use shared data,
because all references to the shared data are serialized.
\li A \e reentrant function can also be called simultaneously from
multiple threads, but only if each invocation uses its own data.
\endlist
Hence, a \e{thread-safe} function is always \e{reentrant}, but a
\e{reentrant} function is not always \e{thread-safe}.
By extension, a class is said to be \e{reentrant} if its member
functions can be called safely from multiple threads, as long as
each thread uses a \e{different} instance of the class. The class
is \e{thread-safe} if its member functions can be called safely
from multiple threads, even if all the threads use the \e{same}
instance of the class.
\note Qt classes are only documented as \e{thread-safe} if they
are intended to be used by multiple threads. If a function is not
marked as thread-safe or reentrant, it should not be used from
different threads. If a class is not marked as thread-safe or
reentrant then a specific instance of that class should not be
accessed from different threads.
\section1 Reentrancy
C++ classes are often reentrant, simply because they only access
their own member data. Any thread can call a member function on an
instance of a reentrant class, as long as no other thread can call
a member function on the \e{same} instance of the class at the
same time. For example, the \c Counter class below is reentrant:
\snippet threads/threads.cpp 3
\snippet threads/threads.cpp 4
The class isn't thread-safe, because if multiple threads try to
modify the data member \c n, the result is undefined. This is
because the \c ++ and \c -- operators aren't always atomic.
Indeed, they usually expand to three machine instructions:
\list 1
\li Load the variable's value in a register.
\li Increment or decrement the register's value.
\li Store the register's value back into main memory.
\endlist
If thread A and thread B load the variable's old value
simultaneously, increment their register, and store it back, they
end up overwriting each other, and the variable is incremented
only once!
\section1 Thread-Safety
Clearly, the access must be serialized: Thread A must perform
steps 1, 2, 3 without interruption (atomically) before thread B
can perform the same steps; or vice versa. An easy way to make
the class thread-safe is to protect all access to the data
members with a QMutex:
\snippet threads/threads.cpp 5
\snippet threads/threads.cpp 6
The QMutexLocker class automatically locks the mutex in its
constructor and unlocks it when the destructor is invoked, at the
end of the function. Locking the mutex ensures that access from
different threads will be serialized. The \c mutex data member is
declared with the \c mutable qualifier because we need to lock
and unlock the mutex in \c value(), which is a const function.
\section1 Notes on Qt Classes
Many Qt classes are \e{reentrant}, but they are not made
\e{thread-safe}, because making them thread-safe would incur the
extra overhead of repeatedly locking and unlocking a QMutex. For
example, QString is reentrant but not thread-safe. You can safely
access \e{different} instances of QString from multiple threads
simultaneously, but you can't safely access the \e{same} instance
of QString from multiple threads simultaneously (unless you
protect the accesses yourself with a QMutex).
Some Qt classes and functions are thread-safe. These are mainly
the thread-related classes (e.g. QMutex) and fundamental functions
(e.g. QCoreApplication::postEvent()).
\note Terminology in the multithreading domain isn't entirely
standardized. POSIX uses definitions of reentrant and thread-safe
that are somewhat different for its C APIs. When using other
object-oriented C++ class libraries with Qt, be sure the
definitions are understood.
*/
/*!
\page threads-qobject.html
\title Threads and QObjects
\previouspage Reentrancy and Thread Safety
\contentspage Thread Support in Qt
\nextpage Thread-Support in Qt Modules
QThread inherits QObject. It emits signals to indicate that the
thread started or finished executing, and provides a few slots as
well.
More interesting is that \l{QObject}s can be used in multiple
threads, emit signals that invoke slots in other threads, and
post events to objects that "live" in other threads. This is
possible because each thread is allowed to have its own event
loop.
\section1 QObject Reentrancy
QObject is reentrant. Most of its non-GUI subclasses, such as
QTimer, QTcpSocket, QUdpSocket and QProcess, are also
reentrant, making it possible to use these classes from multiple
threads simultaneously. Note that these classes are designed to be
created and used from within a single thread; creating an object
in one thread and calling its functions from another thread is not
guaranteed to work. There are three constraints to be aware of:
\list
\li \e{The child of a QObject must always be created in the thread
where the parent was created.} This implies, among other
things, that you should never pass the QThread object (\c
this) as the parent of an object created in the thread (since
the QThread object itself was created in another thread).
\li \e{Event driven objects may only be used in a single thread.}
Specifically, this applies to the \l{timers.html}{timer
mechanism} and the \l{QtNetwork}{network module}. For example,
you cannot start a timer or connect a socket in a thread that
is not the \l{QObject::thread()}{object's thread}.
\li \e{You must ensure that all objects created in a thread are
deleted before you delete the QThread.} This can be done
easily by creating the objects on the stack in your
\l{QThread::run()}{run()} implementation.
\endlist
Although QObject is reentrant, the GUI classes, notably QWidget
and all its subclasses, are not reentrant. They can only be used
from the main thread. As noted earlier, QCoreApplication::exec()
must also be called from that thread.
In practice, the impossibility of using GUI classes in other
threads than the main thread can easily be worked around by
putting time-consuming operations in a separate worker thread and
displaying the results on screen in the main thread when the
worker thread is finished. This is the approach used for
implementing the \l{Mandelbrot Example} and
the \l{network/blockingfortuneclient}{Blocking Fortune Client}
example.
\section1 Per-Thread Event Loop
Each thread can have its own event loop. The initial thread
starts its event loops using QCoreApplication::exec(); other
threads can start an event loop using QThread::exec(). Like
QCoreApplication, QThread provides an
\l{QThread::exit()}{exit(int)} function and a
\l{QThread::quit()}{quit()} slot.
An event loop in a thread makes it possible for the thread to use
certain non-GUI Qt classes that require the presence of an event
loop (such as QTimer, QTcpSocket, and QProcess). It also makes it
possible to connect signals from any threads to slots of a
specific thread. This is explained in more detail in the
\l{Signals and Slots Across Threads} section below.
\image threadsandobjects.png Threads, objects, and event loops
A QObject instance is said to \e live in the thread in which it
is created. Events to that object are dispatched by that thread's
event loop. The thread in which a QObject lives is available using
QObject::thread().
Note that for QObjects that are created before QApplication,
QObject::thread() returns zero. This means that the main thread
will only handle posted events for these objects; other event
processing is not done at all for objects with no thread. Use the
QObject::moveToThread() function to change the thread affinity for
an object and its children (the object cannot be moved if it has a
parent).
Calling \c delete on a QObject from a thread other than the one
that \e owns the object (or accessing the object in other ways) is
unsafe, unless you guarantee that the object isn't processing
events at that moment. Use QObject::deleteLater() instead, and a
\l{QEvent::DeferredDelete}{DeferredDelete} event will be posted,
which the event loop of the object's thread will eventually pick
up. By default, the thread that \e owns a QObject is the thread
that \e creates the QObject, but not after QObject::moveToThread()
has been called.
If no event loop is running, events won't be delivered to the
object. For example, if you create a QTimer object in a thread but
never call \l{QThread::exec()}{exec()}, the QTimer will never emit
its \l{QTimer::timeout()}{timeout()} signal. Calling
\l{QObject::deleteLater()}{deleteLater()} won't work
either. (These restrictions apply to the main thread as well.)
You can manually post events to any object in any thread at any
time using the thread-safe function
QCoreApplication::postEvent(). The events will automatically be
dispatched by the event loop of the thread where the object was
created.
Event filters are supported in all threads, with the restriction
that the monitoring object must live in the same thread as the
monitored object. Similarly, QCoreApplication::sendEvent()
(unlike \l{QCoreApplication::postEvent()}{postEvent()}) can only
be used to dispatch events to objects living in the thread from
which the function is called.
\section1 Accessing QObject Subclasses from Other Threads
QObject and all of its subclasses are not thread-safe. This
includes the entire event delivery system. It is important to keep
in mind that the event loop may be delivering events to your
QObject subclass while you are accessing the object from another
thread.
If you are calling a function on an QObject subclass that doesn't
live in the current thread and the object might receive events,
you must protect all access to your QObject subclass's internal
data with a mutex; otherwise, you may experience crashes or other
undesired behavior.
Like other objects, QThread objects live in the thread where the
object was created -- \e not in the thread that is created when
QThread::run() is called. It is generally unsafe to provide slots
in your QThread subclass, unless you protect the member variables
with a mutex.
On the other hand, you can safely emit signals from your
QThread::run() implementation, because signal emission is
thread-safe.
\section1 Signals and Slots Across Threads
Qt supports these signal-slot connection types:
\list
\li \l{Qt::AutoConnection}{Auto Connection} (default) If the signal is
emitted in the thread which the receiving object has affinity then
the behavior is the same as the Direct Connection. Otherwise,
the behavior is the same as the Queued Connection."
\li \l{Qt::DirectConnection}{Direct Connection} The slot is invoked
immediately, when the signal is emitted. The slot is executed
in the emitter's thread, which is not necessarily the
receiver's thread.
\li \l{Qt::QueuedConnection}{Queued Connection} The slot is invoked
when control returns to the event loop of the receiver's
thread. The slot is executed in the receiver's thread.
\li \l{Qt::BlockingQueuedConnection}{Blocking Queued Connection}
The slot is invoked as for the Queued Connection, except the
current thread blocks until the slot returns. \note Using this
type to connect objects in the same thread will cause deadlock.
\li \l{Qt::UniqueConnection}{Unique Connection} The behavior is the
same as the Auto Connection, but the connection is made only if
it does not duplicate an existing connection. i.e., if the same
signal is already connected to the same slot for the same pair
of objects, then the connection is not made and connect()
returns \c false.
\endlist
The connection type can be specified by passing an additional
argument to \l{QObject::connect()}{connect()}. Be aware that
using direct connections when the sender and receiver live in
different threads is unsafe if an event loop is running in the
receiver's thread, for the same reason that calling any function
on an object living in another thread is unsafe.
QObject::connect() itself is thread-safe.
The \l{Mandelbrot Example} uses a queued
connection to communicate between a worker thread and the main
thread. To avoid freezing the main thread's event loop (and, as a
consequence, the application's user interface), all the
Mandelbrot fractal computation is done in a separate worker
thread. The thread emits a signal when it is done rendering the
fractal.
Similarly, the \l{network/blockingfortuneclient}{Blocking Fortune
Client} example uses a separate thread for communicating with
a TCP server asynchronously.
*/
/*!
\page threads-modules.html
\title Thread-Support in Qt Modules
\previouspage Threads and QObjects
\contentspage Thread Support in Qt
\section1 Threads and the SQL Module
A connection can only be used from within the thread that created it.
Moving connections between threads or creating queries from a different
thread is not supported.
In addition, the third party libraries used by the QSqlDrivers can impose
further restrictions on using the SQL Module in a multithreaded program.
Consult the manual of your database client for more information
\section1 Painting in Threads
QPainter can be used in a thread to paint onto QImage, QPrinter, and
QPicture paint devices. Painting onto QPixmaps and QWidgets is \e not
supported. On Mac OS X the automatic progress dialog will not be
displayed if you are printing from outside the GUI thread.
Any number of threads can paint at any given time, however only
one thread at a time can paint on a given paint device. In other
words, two threads can paint at the same time if each paints onto
separate QImages, but the two threads cannot paint onto the same
QImage at the same time.
\section1 Threads and Rich Text Processing
The QTextDocument, QTextCursor, and \l{richtext.html}{all related classes} are reentrant.
Note that a QTextDocument instance created in the GUI thread may
contain QPixmap image resources. Use QTextDocument::clone() to
create a copy of the document, and pass the copy to another thread for
further processing (such as printing).
\section1 Threads and the SVG module
The QSvgGenerator and QSvgRenderer classes in the QtSvg module
are reentrant.
\section1 Threads and Implicitly Shared Classes
Qt uses an optimization called \l{implicit sharing} for many of
its value class, notably QImage and QString. Beginning with Qt 4,
implicit shared classes can safely be copied across threads, like
any other value classes. They are fully
\l{Reentrancy and Thread-Safety}{reentrant}. The implicit sharing
is really \e implicit.
In many people's minds, implicit sharing and multithreading are
incompatible concepts, because of the way the reference counting
is typically done. Qt, however, uses atomic reference counting to
ensure the integrity of the shared data, avoiding potential
corruption of the reference counter.
Note that atomic reference counting does not guarantee
\l{Reentrancy and Thread-Safety}{thread-safety}. Proper locking should be used
when sharing an instance of an implicitly shared class between
threads. This is the same requirement placed on all
\l{Reentrancy and Thread-Safety}{reentrant} classes, shared or not. Atomic reference
counting does, however, guarantee that a thread working on its
own, local instance of an implicitly shared class is safe. We
recommend using \l{Signals and Slots Across Threads}{signals and
slots} to pass data between threads, as this can be done without
the need for any explicit locking.
To sum it up, implicitly shared classes in Qt 4 are really \e
implicitly shared. Even in multithreaded applications, you can
safely use them as if they were plain, non-shared, reentrant
value-based classes.
*/
|