source: trunk/doc/html/threads.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 16.3 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/threads.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Thread Support in Qt</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Thread Support in Qt</h1>
33
34
35<p> <!-- toc -->
36<ul>
37<li><a href="#1"> Introduction
38</a>
39<li><a href="#2"> Enabling Thread Support
40</a>
41<li><a href="#3"> The Thread Classes
42</a>
43<li><a href="#4"> Important Definitions
44</a>
45<li><a href="#5"> Thread-safe Event Posting
46</a>
47<li><a href="#6"> Threads and QObject subclasses
48</a>
49<li><a href="#7"> The Qt Library Mutex
50</a>
51<li><a href="#8"> Threads and Signals and Slots
52</a>
53<li><a href="#9"> Threads and Shared Data
54</a>
55<li><a href="#10"> Threads and the SQL Module
56</a>
57<li><a href="#11"> Caveats
58</a>
59<li><a href="#12"> Recommended Reading
60</a>
61</ul>
62<!-- endtoc -->
63
64<p> <h2> Introduction
65</h2>
66<a name="1"></a><p> Qt provides thread support in the form of basic platform-independent
67threading classes, a thread-safe way of posting events, and a global
68Qt library lock that allows you to call Qt methods from different
69threads.
70<p> This document is intended for an audience that has knowledge of, and
71experience with, multithreaded applications. If you are new to
72threading see our <a href="#reading">Recommended Reading</a> list.
73<p> <h2> Enabling Thread Support
74</h2>
75<a name="2"></a><p> When Qt is installed on Windows, thread support is an option on some
76compilers.
77<p> On Mac OS X and Unix, thread support is enabled by adding the
78<tt>-thread</tt> option when running the <tt>configure</tt> script. On Unix
79platforms where multithreaded programs must be linked in special ways,
80such as with a special libc, installation will create a separate
81library, <tt>libqt-mt</tt> and hence threaded programs must be linked
82against this library (with <tt>-lqt-mt</tt>) rather than the standard Qt
83library.
84<p> On both platforms, you should compile with the macro <tt>QT_THREAD_SUPPORT</tt> defined (e.g. compile with
85<tt>-DQT_THREAD_SUPPORT</tt>). On Windows, this is usually done by an
86entry in <tt>qconfig.h</tt>.
87<p> <h2> The Thread Classes
88</h2>
89<a name="3"></a><p> These classes are built into the Qt library when thread support is enabled:
90<p> <ul>
91<li> <a href="qthread.html">QThread</a> - Provides the means to start a new thread, which begins
92execution in your reimplementation of <a href="qthread.html#run">QThread::run</a>(). This is similar
93to the Java thread class.
94<p> <li> <a href="qthreadstorage.html">QThreadStorage</a> - Provides per-thread data storage. This class can
95only be used with threads started with QThread; it cannot be used with
96threads started with platform-specific APIs.
97<p> <li> <a href="qmutex.html">QMutex</a> - Provides a mutual exclusion lock (also know as a mutex).
98<li> <a href="qmutexlocker.html">QMutexLocker</a> - A convenience class which automatically locks and
99unlocks a QMutex. QMutexLocker is useful in complicated code, or in
100code which uses exceptions. See the documentation for more details.
101<li> <a href="qwaitcondition.html">QWaitCondition</a> - Provides a way for threads to go to sleep until
102woken up by another thread.
103<li> <a href="qsemaphore.html">QSemaphore</a> - Provides a simple integer semaphore.
104</ul>
105<p> <h2> Important Definitions
106</h2>
107<a name="4"></a><p> <a name="reentrant"></a>
108<a name="threadsafe"></a>
109<p> When using Qt in a multithreaded program, it is important to
110understand the definition of the terms <em>reentrant</em> and <em>thread-safe</em>:
111<p> <ul>
112<li> <em>reentrant</em> - Describes a function which can be called
113simultaneously by multiple threads when each invocation of the
114function references unique data. Calling a reentrant function
115simultaneously with the same data is not safe, and such invocations
116should be serialized.
117<li> <em>thread-safe</em> - Describes a function which can be called
118simultaneously by multiple threads when each invocation references
119shared data. Calling a thread-safe function simultaneously with the
120same data is safe, since all access to the shared data are serialized.
121</ul>
122<p> Note that Qt provides both implictly and <a href="shclass.html#explicitly-shared">explicitly shared</a>
123classes. For more information, see the <a href="threads.html#threads-shared">Threads and Shared Data</a>
124section.
125<p> Most C++ member functions are inherently reentrant, since they only
126reference class member data. Any thread can call such a member
127function on an instance, as long as no other thread is calling a
128member function on the same instance. For example, given the class <tt>Number</tt> below:
129<p> <pre>
130 class Number
131 {
132 public:
133 inline Number( int n ) : num( n ) { }
134
135 inline int number() const { return num; }
136 inline void setNumber( int n ) { num = n; }
137
138 private:
139 int num;
140 };
141</pre>
142
143<p> The methods <tt>Number::number()</tt> and <tt>Number::setNumber()</tt> are
144reentrant, since they only reference unique data. Only one thread at
145a time can call member functions on each instance of <tt>Number</tt>.
146However, multiple threads can call member functions on separate
147instances of <tt>Number</tt>.
148<p> Thread-safe functions usually use a mutex (e.g a <a href="qmutex.html">QMutex</a>) to serialize
149access to shared data. Because of this, thread-safe functions are
150usually slower than reentrant functions, because of the extra overhead
151of locking and unlocking the mutex. For example, given the class <tt>Counter</tt> below:
152<p> <pre>
153 class Counter
154 {
155 public:
156 inline Counter() { ++instances; }
157 inline ~Counter() { --instances; }
158
159 private:
160 static int instances;
161 };
162</pre>
163
164<p> Since the modifications of the static <tt>instances</tt> integer are not
165serialized, this class is not thread-safe. So make it threadsafe, a
166mutex must be used:
167<p> <pre>
168 class Counter
169 {
170 public:
171 inline Counter()
172 {
173 mutex.lock();
174 ++instances;
175 mutex.unlock();
176 }
177
178 ...
179 private:
180 static QMutex mutex;
181 static int instances;
182 };
183</pre>
184
185<p> <h2> Thread-safe Event Posting
186</h2>
187<a name="5"></a><p> In Qt, one thread is always the GUI or event thread. This is the
188thread that creates a <a href="qapplication.html">QApplication</a> object and calls
189<a href="qapplication.html#exec">QApplication::exec</a>(). This is also the initial thread that calls
190main() at program start. This thread is the only thread that is
191allowed to perform GUI operations, including generating and receiving
192events from the window system. Qt does not support creating
193QApplication and running the event loop (with QApplication::exec()) in
194a secondary thread. You must create the QApplication object and call
195QApplication::exec() from the main() function in your program.
196<p> Threads that wish to display data in a widget cannot modify the widget
197directly, so they must post an event to the widget using
198<a href="qapplication.html#postEvent">QApplication::postEvent</a>(). The event will be delivered later on by
199the GUI thread.
200<p> Normally, the programmer would like to include some information in the
201event sent to the widget. See the documentation for <a href="qcustomevent.html">QCustomEvent</a> for
202more information on user-defined events.
203<p> <h2> Threads and <a href="qobject.html">QObject</a> subclasses
204</h2>
205<a name="6"></a><p> The QObject class itself is <em>reentrant</em>. However, certain rules
206apply when creating and using QObjects in a thread that is not the GUI
207thread.
208<p> <ol type=1>
209<p> <li> <em>None</em> of the QObject based classes included in the Qt library are
210<em>reentrant</em>. This includes all widgets (e.g. <a href="qwidget.html">QWidget</a> and
211subclasses), OS kernel classes (e.g. <a href="qprocess.html">QProcess</a>, <a href="qaccel.html">QAccel</a>, <a href="qtimer.html">QTimer</a>), and
212all networking classes (e.g. <a href="qsocket.html">QSocket</a>, <a href="qdns.html">QDns</a>).
213<p> <li> QObject and all of its subclasses are <em>not</em> <em>thread-safe</em>. This
214includes the entire event delivery system. It is important to
215remember that the GUI thread may be delivering events to your QObject
216subclass while you are accessing the object from another thread. If
217you are using QObject in a thread that is not the GUI thread, and you
218are handling events sent to this object, you <em>must</em> protect all
219access to your data with a mutex; otherwise you may experience crashes
220or other undesired behavior.
221<p> <li> As a corollary to the above, deleting a <a href="qobject.html">QObject</a> while pending
222events are waiting to be delivered can cause a crash. You must not
223delete the QObject directly from a thread that is not the GUI thread.
224Use the <a href="qobject.html#deleteLater">QObject::deleteLater</a>() method instead, which will cause the
225event loop to delete the object after all pending events have been
226delivered to the object.
227<p> </ol>
228<p> <h2> The Qt Library Mutex
229</h2>
230<a name="7"></a><p> <a href="qapplication.html">QApplication</a> includes a mutex that is used to protect access to window
231system functions. This mutex is locked while the event loop is
232running (e.g. during event delivery) and unlocked when the eventloop
233goes to sleep. Note: The Qt event loop is recursive, and the library
234mutex is <em>not</em> unlocked when re-entering the event loop (e.g. when
235executing a modal dialog with <a href="qdialog.html#exec">QDialog::exec</a>()).
236<p> If another thread locks the Qt library mutex, then the event loop will
237stop processing events, and the locking thread may do simple GUI
238operations. Operations such as creating a <a href="qpainter.html">QPainter</a> and drawing a line
239are examples of simple GUI operations:
240<p> <pre>
241 ...
242 qApp-&gt;<a href="qapplication.html#lock">lock</a>();
243
244 <a href="qpainter.html">QPainter</a> p;
245 p.<a href="qpainter.html#begin">begin</a>( mywidget );
246 p.<a href="qpainter.html#setPen">setPen</a>( QColor( "red" ) );
247 p.<a href="qpainter.html#drawLine">drawLine</a>( 0,0,100,100 );
248 p.<a href="qpainter.html#end">end</a>();
249
250 qApp-&gt;<a href="qapplication.html#unlock">unlock</a>();
251 ...
252</pre>
253
254<p> Any operations that generate events must not be called by any thread
255other than the GUI thread. Examples of such operations are:
256<p> <ul>
257<li> creating a <a href="qwidget.html">QWidget</a>, <a href="qtimer.html">QTimer</a>, <a href="qsocketnotifier.html">QSocketNotifier</a>, <a href="qsocket.html">QSocket</a> or other network class.
258<li> moving, resizing, showing or hiding a QWidget.
259<li> starting or stoping a QTimer.
260<li> enabling or disabling a QSocketNotifier.
261<li> using a QSocket or other network class.
262</ul>
263<p> Events generated by these operations will be lost on some platforms.
264<p> <h2> Threads and Signals and Slots
265</h2>
266<a name="8"></a><p> The Signals and Slots mechanism can be used in separate threads, as
267long as the rules for <a href="qobject.html">QObject</a> based classes are followed. The Signals
268and Slots mechanism is synchronous: when a signal is emitted, all
269slots are called immediately. The slots are executed in the thread
270context that emitted the signal.
271<p> <b>Warning:</b> Slots that generate window system events or use window system
272functions <em>must</em> <em>not</em> be connected to a signal that is emitted from
273a thread that is not the GUI thread. See the Qt Library Mutex section
274above for more details.
275<p> <a name="threads-shared"></a>
276<h2> Threads and Shared Data
277</h2>
278<a name="9"></a><p> Qt provides many <a href="shclass.html#implicitly-shared">implicitly shared</a> and explicitly shared classes. In
279a multithreaded program, multiple instances of a shared class can
280reference shared data, which is dangerous if one or more threads
281attempt to modify the data. Qt provides the <a href="qdeepcopy.html">QDeepCopy</a> class, which
282ensures that shared classes reference unique data.
283<p> See the description of <a href="shclass.html">implicit sharing</a> for more
284information.
285<p> <a name="threads-sql"></a>
286<h2> Threads and the SQL Module
287</h2>
288<a name="10"></a><p> A connection can only be used from within the thread that created it.
289Moving connections between threads or creating queries from a different
290thread is not supported.
291<p> In addition, the third party libraries used by the QSqlDrivers can impose
292further restrictions on using the SQL Module in a multithreaded program.
293Consult the manual of your database client for more information.
294<p> <h2> Caveats
295</h2>
296<a name="11"></a><p> Some things to watch out for when programming with threads:
297<p> <ul>
298<p> <li> As mentioned above, <a href="qobject.html">QObject</a> based classes are neither thread-safe
299nor reentrant. This includes all widgets (e.g. <a href="qwidget.html">QWidget</a> and
300subclasses), OS kernel classes (e.g. <a href="qprocess.html">QProcess</a>, <a href="qaccel.html">QAccel</a>), and all
301networking classes (e.g. <a href="qsocket.html">QSocket</a>, <a href="qdns.html">QDns</a>).
302<p> <li> Deleting a QObject while pending events are waiting to be delivered
303will cause a crash. If you are creating QObjects in a thread that is
304not the GUI thread and posting events to these objects, you should not
305delete the QObject directly. Use the <a href="qobject.html#deleteLater">QObject::deleteLater</a>() method
306instead, which will cause the event loop to delete the object after
307all pending events have been delivered to the object.
308<p> <li> Don't do any blocking operations while holding the Qt library
309mutex. This will freeze up the event loop.
310<p> <li> Make sure you unlock a recursive <a href="qmutex.html">QMutex</a> as many times as you lock
311it, no more and no less.
312<p> <li> Don't mix the normal Qt library and the threaded Qt library in your
313application. This means that if your application uses the threaded Qt
314library, you should not link with the normal Qt library, dynamically
315load the normal Qt library or dynamically load another library or
316plugin that depends on the normal Qt library. On some systems, doing
317this can corrupt the static data used in the Qt library.
318<p> <li> Qt does not support creating <a href="qapplication.html">QApplication</a> and running the event
319loop (with <a href="qapplication.html#exec">QApplication::exec</a>()) in a secondary thread. You must
320create the QApplication object and call QApplication::exec() from the
321main() function in your program.
322<p> </ul>
323<p> <a name="reading"></a>
324<h2> Recommended Reading
325</h2>
326<a name="12"></a><p> <ul>
327<li> <a href="http://www.amazon.com/exec/obidos/ASIN/0134436989/trolltech/t">Threads Primer: A Guide to Multithreaded Programming</a>
328<li> <a href="http://www.amazon.com/exec/obidos/ASIN/0131900676/trolltech/t">Thread Time: The Multithreaded Programming Guide</a>
329<li> <a href="http://www.amazon.com/exec/obidos/ASIN/1565921151/trolltech/t">Pthreads Programming: A POSIX Standard for Better Multiprocessing (O'Reilly Nutshell)</a>
330<li> <a href="http://www.amazon.com/exec/obidos/ASIN/1565922964/trolltech/t">Win32 Multithreaded Programming</a>
331</ul>
332<p>
333<!-- eof -->
334<p><address><hr><div align=center>
335<table width=100% cellspacing=0 border=0><tr>
336<td>Copyright &copy; 2007
337<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
338<td align=right><div align=right>Qt 3.3.8</div>
339</table></div></address></body>
340</html>
Note: See TracBrowser for help on using the repository browser.