From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqwaitcondition.html | 197 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 doc/html/ntqwaitcondition.html (limited to 'doc/html/ntqwaitcondition.html') diff --git a/doc/html/ntqwaitcondition.html b/doc/html/ntqwaitcondition.html new file mode 100644 index 000000000..c497b58a2 --- /dev/null +++ b/doc/html/ntqwaitcondition.html @@ -0,0 +1,197 @@ + + + + + +TQWaitCondition Class + + + + + + + +

TQWaitCondition Class Reference

+ +

The TQWaitCondition class allows waiting/waking for conditions between threads. +More... +

All the functions in this class are thread-safe when TQt is built with thread support.

#include <ntqwaitcondition.h> +

List of all member functions. +

Public Members

TQWaitCondition ()
virtual ~TQWaitCondition ()
bool wait ( unsigned long time = ULONG_MAX )
bool wait ( TQMutex * mutex, unsigned long time = ULONG_MAX )
void wakeOne ()
void wakeAll ()

Detailed Description

+ + + +The TQWaitCondition class allows waiting/waking for conditions between threads. +

+ +

TQWaitConditions allow a thread to tell other threads that some +sort of condition has been met; one or many threads can block +waiting for a TQWaitCondition to set a condition with wakeOne() or +wakeAll(). Use wakeOne() to wake one randomly selected event or +wakeAll() to wake them all. For example, say we have three tasks +that should be performed every time the user presses a key; each +task could be split into a thread, each of which would have a +run() body like this: +

+    TQWaitCondition key_pressed;
+
+    for (;;) {
+        key_pressed.wait(); // This is a TQWaitCondition global variable
+        // Key was pressed, do something interesting
+        do_something();
+    }
+

+ +

A fourth thread would read key presses and wake the other three +threads up every time it receives one, like this: +

+    TQWaitCondition key_pressed;
+
+    for (;;) {
+        getchar();
+        // Causes any thread in key_pressed.wait() to return from
+        // that method and continue processing
+        key_pressed.wakeAll();
+    }
+

+ +

Note that the order the three threads are woken up in is +undefined, and that if some or all of the threads are still in +do_something() when the key is pressed, they won't be woken up +(since they're not waiting on the condition variable) and so the +task will not be performed for that key press. This can be +avoided by, for example, doing something like this: +

+    TQMutex mymutex;
+    TQWaitCondition key_pressed;
+    int mycount=0;
+
+    // Worker thread code
+    for (;;) {
+        key_pressed.wait(); // This is a TQWaitCondition global variable
+        mymutex.lock();
+        mycount++;
+        mymutex.unlock();
+        do_something();
+        mymutex.lock();
+        mycount--;
+        mymutex.unlock();
+    }
+
+    // Key reading thread code
+    for (;;) {
+        getchar();
+        mymutex.lock();
+        // Sleep until there are no busy worker threads
+        while( mycount > 0 ) {
+            mymutex.unlock();
+            sleep( 1 );
+            mymutex.lock();
+        }
+        mymutex.unlock();
+        key_pressed.wakeAll();
+    }
+

+ +

The mutexes are necessary because the results of two threads +attempting to change the value of the same variable simultaneously +are unpredictable. +

See also Environment Classes and Threading. + +

Member Function Documentation

TQWaitCondition::TQWaitCondition () +

+Constructs a new event signalling, i.e. wait condition, object. + +

TQWaitCondition::~TQWaitCondition () `[virtual]` +

+Deletes the event signalling, i.e. wait condition, object. + +

bool TQWaitCondition::wait ( unsigned long time = ULONG_MAX ) +

+Wait on the thread event object. The thread calling this will +block until either of these conditions is met: +

Another thread signals it using wakeOne() or wakeAll(). This +function will return TRUE in this case. +
time milliseconds has elapsed. If time is ULONG_MAX (the +default), then the wait will never timeout (the event must be +signalled). This function will return FALSE if the wait timed +out. +

bool TQWaitCondition::wait ( TQMutex * mutex, unsigned long time = ULONG_MAX ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Release the locked mutex and wait on the thread event object. +The mutex must be initially locked by the calling thread. If mutex is not in a locked state, this function returns immediately. +If mutex is a recursive mutex, this function returns +immediately. The mutex will be unlocked, and the calling thread +will block until either of these conditions is met: +

Another thread signals it using wakeOne() or wakeAll(). This +function will return TRUE in this case. +
time milliseconds has elapsed. If time is ULONG_MAX (the +default), then the wait will never timeout (the event must be +signalled). This function will return FALSE if the wait timed +out. +

The mutex will be returned to the same locked state. This function +is provided to allow the atomic transition from the locked state +to the wait state. +

void TQWaitCondition::wakeAll () +

+This wakes all threads waiting on the TQWaitCondition. The order in +which the threads are woken up depends on the operating system's +scheduling policies, and cannot be controlled or predicted. +

void TQWaitCondition::wakeOne () +

+This wakes one thread waiting on the TQWaitCondition. The thread +that is woken up depends on the operating system's scheduling +policies, and cannot be controlled or predicted. +