Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

author: Timothy Pearson <[email protected]> 2011-11-08 12:31:36 -0600
committer: Timothy Pearson <[email protected]> 2011-11-08 12:31:36 -0600
commit: d796c9dd933ab96ec83b9a634feedd5d32e1ba3f (patch)
tree: 6e3dcca4f77e20ec8966c666aac7c35bd4704053 /doc/html/threads.html
download: tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.tar.gz
tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.zip
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&nbsp;Classes</font></a>
+ | <a href="mainclasses.html">
+<font color="#004faf">Main&nbsp;Classes</font></a>
+ | <a href="annotated.html">
+<font color="#004faf">Annotated</font></a>
+ | <a href="groups.html">
+<font color="#004faf">Grouped&nbsp;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-&gt;<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-&gt;<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 &copy; 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>
author	Timothy Pearson <[email protected]>	2011-11-08 12:31:36 -0600
committer	Timothy Pearson <[email protected]>	2011-11-08 12:31:36 -0600
commit	d796c9dd933ab96ec83b9a634feedd5d32e1ba3f (patch)
tree	6e3dcca4f77e20ec8966c666aac7c35bd4704053 /doc/html/threads.html
download	tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.tar.gz tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.zip