diff options
Diffstat (limited to 'doc/html/threads.html')
| -rw-r--r-- | doc/html/threads.html | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/doc/html/threads.html b/doc/html/threads.html new file mode 100644 index 000000000..5d5d1e7ea --- /dev/null +++ b/doc/html/threads.html @@ -0,0 +1,340 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/threads.doc:36 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Thread Support in TQt</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<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 TQt</h1> + + +<p> <!-- toc --> +<ul> +<li><a href="#1"> Introduction +</a> +<li><a href="#2"> Enabling Thread Support +</a> +<li><a href="#3"> The Thread Classes +</a> +<li><a href="#4"> Important Definitions +</a> +<li><a href="#5"> Thread-safe Event Posting +</a> +<li><a href="#6"> Threads and TQObject subclasses +</a> +<li><a href="#7"> The TQt Library Mutex +</a> +<li><a href="#8"> Threads and Signals and Slots +</a> +<li><a href="#9"> Threads and Shared Data +</a> +<li><a href="#10"> Threads and the SQL Module +</a> +<li><a href="#11"> Caveats +</a> +<li><a href="#12"> Recommended Reading +</a> +</ul> +<!-- endtoc --> + +<p> <h2> Introduction +</h2> +<a name="1"></a><p> TQt provides thread support in the form of basic platform-independent +threading classes, a thread-safe way of posting events, and a global +TQt library lock that allows you to call TQt methods from different +threads. +<p> This document is intended for an audience that has knowledge of, and +experience with, multithreaded applications. If you are new to +threading see our <a href="#reading">Recommended Reading</a> list. +<p> <h2> Enabling Thread Support +</h2> +<a name="2"></a><p> When TQt is installed on Windows, thread support is an option on some +compilers. +<p> On Mac OS X and Unix, thread support is enabled by adding the +<tt>-thread</tt> option when running the <tt>configure</tt> script. On Unix +platforms where multithreaded programs must be linked in special ways, +such as with a special libc, installation will create a separate +library, <tt>libtqt-mt</tt> and hence threaded programs must be linked +against this library (with <tt>-ltqt-mt</tt>) rather than the standard TQt +library. +<p> On both platforms, you should compile with the macro <tt>QT_THREAD_SUPPORT</tt> defined (e.g. compile with +<tt>-DQT_THREAD_SUPPORT</tt>). On Windows, this is usually done by an +entry in <tt>qconfig.h</tt>. +<p> <h2> The Thread Classes +</h2> +<a name="3"></a><p> These classes are built into the TQt library when thread support is enabled: +<p> <ul> +<li> <a href="qthread.html">TQThread</a> - Provides the means to start a new thread, which begins +execution in your reimplementation of <a href="qthread.html#run">TQThread::run</a>(). This is similar +to the Java thread class. +<p> <li> <a href="qthreadstorage.html">TQThreadStorage</a> - Provides per-thread data storage. This class can +only be used with threads started with TQThread; it cannot be used with +threads started with platform-specific APIs. +<p> <li> <a href="qmutex.html">TQMutex</a> - Provides a mutual exclusion lock (also know as a mutex). +<li> <a href="qmutexlocker.html">TQMutexLocker</a> - A convenience class which automatically locks and +unlocks a TQMutex. TQMutexLocker is useful in complicated code, or in +code which uses exceptions. See the documentation for more details. +<li> <a href="qwaitcondition.html">TQWaitCondition</a> - Provides a way for threads to go to sleep until +woken up by another thread. +<li> <a href="qsemaphore.html">TQSemaphore</a> - Provides a simple integer semaphore. +</ul> +<p> <h2> Important Definitions +</h2> +<a name="4"></a><p> <a name="reentrant"></a> +<a name="threadsafe"></a> +<p> When using TQt in a multithreaded program, it is important to +understand the definition of the terms <em>reentrant</em> and <em>thread-safe</em>: +<p> <ul> +<li> <em>reentrant</em> - Describes a function which can be called +simultaneously by multiple threads when each invocation of the +function references unique data. Calling a reentrant function +simultaneously with the same data is not safe, and such invocations +should be serialized. +<li> <em>thread-safe</em> - Describes a function which can be called +simultaneously by multiple threads when each invocation references +shared data. Calling a thread-safe function simultaneously with the +same data is safe, since all access to the shared data are serialized. +</ul> +<p> Note that TQt provides both implictly and <a href="shclass.html#explicitly-shared">explicitly shared</a> +classes. For more information, see the <a href="threads.html#threads-shared">Threads and Shared Data</a> +section. +<p> Most C++ member functions are inherently reentrant, since they only +reference class member data. Any thread can call such a member +function on an instance, as long as no other thread is calling a +member function on the same instance. For example, given the class <tt>Number</tt> below: +<p> <pre> + class Number + { + public: + inline Number( int n ) : num( n ) { } + + inline int number() const { return num; } + inline void setNumber( int n ) { num = n; } + + private: + int num; + }; +</pre> + +<p> The methods <tt>Number::number()</tt> and <tt>Number::setNumber()</tt> are +reentrant, since they only reference unique data. Only one thread at +a time can call member functions on each instance of <tt>Number</tt>. +However, multiple threads can call member functions on separate +instances of <tt>Number</tt>. +<p> Thread-safe functions usually use a mutex (e.g a <a href="qmutex.html">TQMutex</a>) to serialize +access to shared data. Because of this, thread-safe functions are +usually slower than reentrant functions, because of the extra overhead +of locking and unlocking the mutex. For example, given the class <tt>Counter</tt> below: +<p> <pre> + class Counter + { + public: + inline Counter() { ++instances; } + inline ~Counter() { --instances; } + + private: + static int instances; + }; +</pre> + +<p> Since the modifications of the static <tt>instances</tt> integer are not +serialized, this class is not thread-safe. So make it threadsafe, a +mutex must be used: +<p> <pre> + class Counter + { + public: + inline Counter() + { + mutex.lock(); + ++instances; + mutex.unlock(); + } + + ... + private: + static TQMutex mutex; + static int instances; + }; +</pre> + +<p> <h2> Thread-safe Event Posting +</h2> +<a name="5"></a><p> In TQt, one thread is always the GUI or event thread. This is the +thread that creates a <a href="qapplication.html">TQApplication</a> object and calls +<a href="qapplication.html#exec">TQApplication::exec</a>(). This is also the initial thread that calls +main() at program start. This thread is the only thread that is +allowed to perform GUI operations, including generating and receiving +events from the window system. TQt does not support creating +TQApplication and running the event loop (with TQApplication::exec()) in +a secondary thread. You must create the TQApplication object and call +TQApplication::exec() from the main() function in your program. +<p> Threads that wish to display data in a widget cannot modify the widget +directly, so they must post an event to the widget using +<a href="qapplication.html#postEvent">TQApplication::postEvent</a>(). The event will be delivered later on by +the GUI thread. +<p> Normally, the programmer would like to include some information in the +event sent to the widget. See the documentation for <a href="qcustomevent.html">TQCustomEvent</a> for +more information on user-defined events. +<p> <h2> Threads and <a href="qobject.html">TQObject</a> subclasses +</h2> +<a name="6"></a><p> The TQObject class itself is <em>reentrant</em>. However, certain rules +apply when creating and using TQObjects in a thread that is not the GUI +thread. +<p> <ol type=1> +<p> <li> <em>None</em> of the TQObject based classes included in the TQt library are +<em>reentrant</em>. This includes all widgets (e.g. <a href="qwidget.html">TQWidget</a> and +subclasses), OS kernel classes (e.g. <a href="qprocess.html">TQProcess</a>, <a href="qaccel.html">TQAccel</a>, <a href="qtimer.html">TQTimer</a>), and +all networking classes (e.g. <a href="qsocket.html">TQSocket</a>, <a href="qdns.html">TQDns</a>). +<p> <li> TQObject and all of its subclasses are <em>not</em> <em>thread-safe</em>. This +includes the entire event delivery system. It is important to +remember that the GUI thread may be delivering events to your TQObject +subclass while you are accessing the object from another thread. If +you are using TQObject in a thread that is not the GUI thread, and you +are handling events sent to this object, you <em>must</em> protect all +access to your data with a mutex; otherwise you may experience crashes +or other undesired behavior. +<p> <li> As a corollary to the above, deleting a <a href="qobject.html">TQObject</a> while pending +events are waiting to be delivered can cause a crash. You must not +delete the TQObject directly from a thread that is not the GUI thread. +Use the <a href="qobject.html#deleteLater">TQObject::deleteLater</a>() method instead, which will cause the +event loop to delete the object after all pending events have been +delivered to the object. +<p> </ol> +<p> <h2> The TQt Library Mutex +</h2> +<a name="7"></a><p> <a href="qapplication.html">TQApplication</a> includes a mutex that is used to protect access to window +system functions. This mutex is locked while the event loop is +running (e.g. during event delivery) and unlocked when the eventloop +goes to sleep. Note: The TQt event loop is recursive, and the library +mutex is <em>not</em> unlocked when re-entering the event loop (e.g. when +executing a modal dialog with <a href="qdialog.html#exec">TQDialog::exec</a>()). +<p> If another thread locks the TQt library mutex, then the event loop will +stop processing events, and the locking thread may do simple GUI +operations. Operations such as creating a <a href="qpainter.html">TQPainter</a> and drawing a line +are examples of simple GUI operations: +<p> <pre> + ... + qApp-><a href="qapplication.html#lock">lock</a>(); + + <a href="qpainter.html">TQPainter</a> p; + p.<a href="qpainter.html#begin">begin</a>( mywidget ); + p.<a href="qpainter.html#setPen">setPen</a>( TQColor( "red" ) ); + p.<a href="qpainter.html#drawLine">drawLine</a>( 0,0,100,100 ); + p.<a href="qpainter.html#end">end</a>(); + + qApp-><a href="qapplication.html#unlock">unlock</a>(); + ... +</pre> + +<p> Any operations that generate events must not be called by any thread +other than the GUI thread. Examples of such operations are: +<p> <ul> +<li> creating a <a href="qwidget.html">TQWidget</a>, <a href="qtimer.html">TQTimer</a>, <a href="qsocketnotifier.html">TQSocketNotifier</a>, <a href="qsocket.html">TQSocket</a> or other network class. +<li> moving, resizing, showing or hiding a TQWidget. +<li> starting or stoping a TQTimer. +<li> enabling or disabling a TQSocketNotifier. +<li> using a TQSocket or other network class. +</ul> +<p> Events generated by these operations will be lost on some platforms. +<p> <h2> Threads and Signals and Slots +</h2> +<a name="8"></a><p> The Signals and Slots mechanism can be used in separate threads, as +long as the rules for <a href="qobject.html">TQObject</a> based classes are followed. The Signals +and Slots mechanism is synchronous: when a signal is emitted, all +slots are called immediately. The slots are executed in the thread +context that emitted the signal. +<p> <b>Warning:</b> Slots that generate window system events or use window system +functions <em>must</em> <em>not</em> be connected to a signal that is emitted from +a thread that is not the GUI thread. See the TQt Library Mutex section +above for more details. +<p> <a name="threads-shared"></a> +<h2> Threads and Shared Data +</h2> +<a name="9"></a><p> TQt provides many <a href="shclass.html#implicitly-shared">implicitly shared</a> and explicitly shared classes. In +a multithreaded program, multiple instances of a shared class can +reference shared data, which is dangerous if one or more threads +attempt to modify the data. TQt provides the <a href="qdeepcopy.html">TQDeepCopy</a> class, which +ensures that shared classes reference unique data. +<p> See the description of <a href="shclass.html">implicit sharing</a> for more +information. +<p> <a name="threads-sql"></a> +<h2> Threads and the SQL Module +</h2> +<a name="10"></a><p> 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. +<p> In addition, the third party libraries used by the TQSqlDrivers can impose +further restrictions on using the SQL Module in a multithreaded program. +Consult the manual of your database client for more information. +<p> <h2> Caveats +</h2> +<a name="11"></a><p> Some things to watch out for when programming with threads: +<p> <ul> +<p> <li> As mentioned above, <a href="qobject.html">TQObject</a> based classes are neither thread-safe +nor reentrant. This includes all widgets (e.g. <a href="qwidget.html">TQWidget</a> and +subclasses), OS kernel classes (e.g. <a href="qprocess.html">TQProcess</a>, <a href="qaccel.html">TQAccel</a>), and all +networking classes (e.g. <a href="qsocket.html">TQSocket</a>, <a href="qdns.html">TQDns</a>). +<p> <li> Deleting a TQObject while pending events are waiting to be delivered +will cause a crash. If you are creating TQObjects in a thread that is +not the GUI thread and posting events to these objects, you should not +delete the TQObject directly. Use the <a href="qobject.html#deleteLater">TQObject::deleteLater</a>() method +instead, which will cause the event loop to delete the object after +all pending events have been delivered to the object. +<p> <li> Don't do any blocking operations while holding the TQt library +mutex. This will freeze up the event loop. +<p> <li> Make sure you unlock a recursive <a href="qmutex.html">TQMutex</a> as many times as you lock +it, no more and no less. +<p> <li> Don't mix the normal TQt library and the threaded TQt library in your +application. This means that if your application uses the threaded TQt +library, you should not link with the normal TQt library, dynamically +load the normal TQt library or dynamically load another library or +plugin that depends on the normal TQt library. On some systems, doing +this can corrupt the static data used in the TQt library. +<p> <li> TQt does not support creating <a href="qapplication.html">TQApplication</a> and running the event +loop (with <a href="qapplication.html#exec">TQApplication::exec</a>()) in a secondary thread. You must +create the TQApplication object and call TQApplication::exec() from the +main() function in your program. +<p> </ul> +<p> <a name="reading"></a> +<h2> Recommended Reading +</h2> +<a name="12"></a><p> <ul> +<li> <a href="http://www.amazon.com/exec/obidos/ASIN/0134436989/trolltech/t">Threads Primer: A Guide to Multithreaded Programming</a> +<li> <a href="http://www.amazon.com/exec/obidos/ASIN/0131900676/trolltech/t">Thread Time: The Multithreaded Programming Guide</a> +<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> +<li> <a href="http://www.amazon.com/exec/obidos/ASIN/1565922964/trolltech/t">Win32 Multithreaded Programming</a> +</ul> +<p> +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>TQt 3.3.8</div> +</table></div></address></body> +</html> |