You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
341 lines
16 KiB
341 lines
16 KiB
<!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>TQT_THREAD_SUPPORT</tt> defined (e.g. compile with
|
|
<tt>-DTQT_THREAD_SUPPORT</tt>). On Windows, this is usually done by an
|
|
entry in <tt>ntqconfig.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="ntqthread.html">TQThread</a> - Provides the means to start a new thread, which begins
|
|
execution in your reimplementation of <a href="ntqthread.html#run">TQThread::run</a>(). This is similar
|
|
to the Java thread class.
|
|
<p> <li> <a href="ntqthreadstorage.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="ntqmutex.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="ntqwaitcondition.html">TQWaitCondition</a> - Provides a way for threads to go to sleep until
|
|
woken up by another thread.
|
|
<li> <a href="ntqsemaphore.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="ntqmutex.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="ntqapplication.html">TQApplication</a> object and calls
|
|
<a href="ntqapplication.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="ntqapplication.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="ntqobject.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="ntqwidget.html">TQWidget</a> and
|
|
subclasses), OS kernel classes (e.g. <a href="ntqprocess.html">TQProcess</a>, <a href="ntqaccel.html">TQAccel</a>, <a href="ntqtimer.html">TQTimer</a>), and
|
|
all networking classes (e.g. <a href="ntqsocket.html">TQSocket</a>, <a href="ntqdns.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="ntqobject.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="ntqobject.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="ntqapplication.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="ntqdialog.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="ntqpainter.html">TQPainter</a> and drawing a line
|
|
are examples of simple GUI operations:
|
|
<p> <pre>
|
|
...
|
|
tqApp-><a href="ntqapplication.html#lock">lock</a>();
|
|
|
|
<a href="ntqpainter.html">TQPainter</a> p;
|
|
p.<a href="ntqpainter.html#begin">begin</a>( mywidget );
|
|
p.<a href="ntqpainter.html#setPen">setPen</a>( TQColor( "red" ) );
|
|
p.<a href="ntqpainter.html#drawLine">drawLine</a>( 0,0,100,100 );
|
|
p.<a href="ntqpainter.html#end">end</a>();
|
|
|
|
tqApp-><a href="ntqapplication.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="ntqwidget.html">TQWidget</a>, <a href="ntqtimer.html">TQTimer</a>, <a href="ntqsocketnotifier.html">TQSocketNotifier</a>, <a href="ntqsocket.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="ntqobject.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="ntqdeepcopy.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="ntqobject.html">TQObject</a> based classes are neither thread-safe
|
|
nor reentrant. This includes all widgets (e.g. <a href="ntqwidget.html">TQWidget</a> and
|
|
subclasses), OS kernel classes (e.g. <a href="ntqprocess.html">TQProcess</a>, <a href="ntqaccel.html">TQAccel</a>), and all
|
|
networking classes (e.g. <a href="ntqsocket.html">TQSocket</a>, <a href="ntqdns.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="ntqobject.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="ntqmutex.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="ntqapplication.html">TQApplication</a> and running the event
|
|
loop (with <a href="ntqapplication.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>
|