From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/threads.html | 340 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 340 insertions(+) create mode 100644 doc/html/threads.html (limited to 'doc/html/threads.html') 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 @@ + + + + + +Thread Support in TQt + + + + + + + +

Thread Support in TQt

+ + +

Introduction + +
Enabling Thread Support + +
The Thread Classes + +
Important Definitions + +
Thread-safe Event Posting + +
Threads and TQObject subclasses + +
The TQt Library Mutex + +
Threads and Signals and Slots + +
Threads and Shared Data + +
Threads and the SQL Module + +
Caveats + +
Recommended Reading + +

+ + +

Introduction +

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. +

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. +

Enabling Thread Support +

When TQt is installed on Windows, thread support is an option on some +compilers. +

On Mac OS X and Unix, thread support is enabled by adding the +-thread option when running the configure 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, libtqt-mt and hence threaded programs must be linked +against this library (with -ltqt-mt) rather than the standard TQt +library. +

On both platforms, you should compile with the macro QT_THREAD_SUPPORT defined (e.g. compile with +-DQT_THREAD_SUPPORT). On Windows, this is usually done by an +entry in qconfig.h. +

The Thread Classes +

These classes are built into the TQt library when thread support is enabled: +

TQThread - Provides the means to start a new thread, which begins +execution in your reimplementation of TQThread::run(). This is similar +to the Java thread class. +
TQThreadStorage - 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. +
TQMutex - Provides a mutual exclusion lock (also know as a mutex). +
TQMutexLocker - 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. +
TQWaitCondition - Provides a way for threads to go to sleep until +woken up by another thread. +
TQSemaphore - Provides a simple integer semaphore. +

Important Definitions +

+ +

When using TQt in a multithreaded program, it is important to +understand the definition of the terms reentrant and thread-safe: +

reentrant - 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. +
thread-safe - 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. +

Note that TQt provides both implictly and explicitly shared +classes. For more information, see the Threads and Shared Data +section. +

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 Number below: +

+    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;
+    };
+

+ +

The methods Number::number() and Number::setNumber() are +reentrant, since they only reference unique data. Only one thread at +a time can call member functions on each instance of Number. +However, multiple threads can call member functions on separate +instances of Number. +

Thread-safe functions usually use a mutex (e.g a TQMutex) 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 Counter below: +

+    class Counter
+    {
+    public:
+        inline Counter()  { ++instances; }
+        inline ~Counter() { --instances; }
+
+    private:
+        static int instances;
+    };
+

+ +

Since the modifications of the static instances integer are not +serialized, this class is not thread-safe. So make it threadsafe, a +mutex must be used: +

+    class Counter
+    {
+    public:
+        inline Counter()
+        {
+            mutex.lock();
+            ++instances;
+            mutex.unlock();
+        }
+
+        ...
+    private:
+        static TQMutex mutex;
+        static int instances;
+    };
+

+ +

Thread-safe Event Posting +

In TQt, one thread is always the GUI or event thread. This is the +thread that creates a TQApplication object and calls +TQApplication::exec(). 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. +

Threads that wish to display data in a widget cannot modify the widget +directly, so they must post an event to the widget using +TQApplication::postEvent(). The event will be delivered later on by +the GUI thread. +

Normally, the programmer would like to include some information in the +event sent to the widget. See the documentation for TQCustomEvent for +more information on user-defined events. +

Threads and TQObject subclasses +

The TQObject class itself is reentrant. However, certain rules +apply when creating and using TQObjects in a thread that is not the GUI +thread. +

None of the TQObject based classes included in the TQt library are +reentrant. This includes all widgets (e.g. TQWidget and +subclasses), OS kernel classes (e.g. TQProcess, TQAccel, TQTimer), and +all networking classes (e.g. TQSocket, TQDns). +
TQObject and all of its subclasses are not thread-safe. 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 must protect all +access to your data with a mutex; otherwise you may experience crashes +or other undesired behavior. +
As a corollary to the above, deleting a TQObject 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 TQObject::deleteLater() method instead, which will cause the +event loop to delete the object after all pending events have been +delivered to the object. +

The TQt Library Mutex +

TQApplication 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 not unlocked when re-entering the event loop (e.g. when +executing a modal dialog with TQDialog::exec()). +

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 TQPainter and drawing a line +are examples of simple GUI operations: +

+    ...
+    qApp->lock();
+
+    TQPainter p;
+    p.begin( mywidget );
+    p.setPen( TQColor( "red" ) );
+    p.drawLine( 0,0,100,100 );
+    p.end();
+
+    qApp->unlock();
+    ...
+

+ +

Any operations that generate events must not be called by any thread +other than the GUI thread. Examples of such operations are: +

creating a TQWidget, TQTimer, TQSocketNotifier, TQSocket or other network class. +
moving, resizing, showing or hiding a TQWidget. +
starting or stoping a TQTimer. +
enabling or disabling a TQSocketNotifier. +
using a TQSocket or other network class. +

Events generated by these operations will be lost on some platforms. +

Threads and Signals and Slots +

The Signals and Slots mechanism can be used in separate threads, as +long as the rules for TQObject 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. +

Warning: Slots that generate window system events or use window system +functions must not 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. +

Threads and Shared Data +

TQt provides many implicitly shared 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 TQDeepCopy class, which +ensures that shared classes reference unique data. +

See the description of implicit sharing for more +information. +

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 TQSqlDrivers can impose +further restrictions on using the SQL Module in a multithreaded program. +Consult the manual of your database client for more information. +

Caveats +

Some things to watch out for when programming with threads: +

As mentioned above, TQObject based classes are neither thread-safe +nor reentrant. This includes all widgets (e.g. TQWidget and +subclasses), OS kernel classes (e.g. TQProcess, TQAccel), and all +networking classes (e.g. TQSocket, TQDns). +
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 TQObject::deleteLater() method +instead, which will cause the event loop to delete the object after +all pending events have been delivered to the object. +
Don't do any blocking operations while holding the TQt library +mutex. This will freeze up the event loop. +
Make sure you unlock a recursive TQMutex as many times as you lock +it, no more and no less. +
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. +
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. +