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/qmutexlocker.html | 220 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 doc/html/qmutexlocker.html (limited to 'doc/html/qmutexlocker.html') diff --git a/doc/html/qmutexlocker.html b/doc/html/qmutexlocker.html new file mode 100644 index 000000000..4c550c4e0 --- /dev/null +++ b/doc/html/qmutexlocker.html @@ -0,0 +1,220 @@ + + + + + +TQMutexLocker Class + + + + + + + +

TQMutexLocker Class Reference

+ +

The TQMutexLocker class simplifies locking and unlocking TQMutexes. +More... +

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

#include <qmutex.h> +

List of all member functions. +

Public Members

TQMutexLocker ( TQMutex * mutex )
~TQMutexLocker ()
TQMutex * mutex () const

Detailed Description

+ + +The TQMutexLocker class simplifies locking and unlocking TQMutexes. +

+ +

The purpose of TQMutexLocker is to simplify TQMutex locking and +unlocking. Locking and unlocking a TQMutex in complex functions and +statements or in exception handling code is error prone and +difficult to debug. TQMutexLocker should be used in such situations +to ensure that the state of the mutex is well defined and always +locked and unlocked properly. +

TQMutexLocker should be created within a function where a TQMutex +needs to be locked. The mutex is locked when TQMutexLocker is +created, and unlocked when TQMutexLocker is destroyed. +

For example, this complex function locks a TQMutex upon entering +the function and unlocks the mutex at all the exit points: +

+    int complexFunction( int flag )
+    {
+        mutex.lock();
+
+        int return_value = 0;
+
+        switch ( flag ) {
+        case 0:
+        case 1:
+            {
+                mutex.unlock();
+                return moreComplexFunction( flag );
+            }
+
+        case 2:
+            {
+                int status = anotherFunction();
+                if ( status < 0 ) {
+                    mutex.unlock();
+                    return -2;
+                }
+                return_value = status + flag;
+                break;
+            }
+
+        default:
+            {
+                if ( flag > 10 ) {
+                    mutex.unlock();
+                    return -1;
+                }
+                break;
+            }
+        }
+
+        mutex.unlock();
+        return return_value;
+    }
+

+ +

This example function will get more complicated as it is +developed, which increases the likelihood that errors will occur. +

Using TQMutexLocker greatly simplifies the code, and makes it more +readable: +

+    int complexFunction( int flag )
+    {
+        TQMutexLocker locker( &mutex );
+
+        int return_value = 0;
+
+        switch ( flag ) {
+        case 0:
+        case 1:
+            {
+                return moreComplexFunction( flag );
+            }
+
+        case 2:
+            {
+                int status = anotherFunction();
+                if ( status < 0 )
+                    return -2;
+                return_value = status + flag;
+                break;
+            }
+
+        default:
+            {
+                if ( flag > 10 )
+                    return -1;
+                break;
+            }
+        }
+
+        return return_value;
+    }
+

+ +

Now, the mutex will always be unlocked when the TQMutexLocker +object is destroyed (when the function returns since locker is +an auto variable). Note that the mutex will be unlocked after +the call to moreComplexFunction() in this example, avoiding +possible bugs caused by unlocking the mutex too early, as in +the first example. +

The same principle applies to code that throws and catches +exceptions. An exception that is not caught in the function that +has locked the mutex has no way of unlocking the mutex before the +exception is passed up the stack to the calling function. +

TQMutexLocker also provides a mutex() member function that returns +the mutex on which the TQMutexLocker is operating. This is useful +for code that needs access to the mutex, such as +TQWaitCondition::wait(). For example: +

+    class SignalWaiter
+    {
+    private:
+        TQMutexLocker locker;
+
+    public:
+        SignalWaiter( TQMutex *mutex )
+            : locker( mutex )
+        {
+        }
+
+        void waitForSignal()
+        {
+            ...
+            ...
+            ...
+
+            while ( ! signalled )
+                waitcondition.wait( locker.mutex() );
+
+            ...
+            ...
+            ...
+        }
+    };
+

+ +

See also TQMutex, TQWaitCondition, Environment Classes, and Threading. + +

Member Function Documentation

TQMutexLocker::TQMutexLocker ( TQMutex * mutex ) +

+ +

Constructs a TQMutexLocker and locks mutex. The mutex will be +unlocked when the TQMutexLocker is destroyed. If mutex is zero, +TQMutexLocker does nothing. +

TQMutexLocker::~TQMutexLocker () +

+ +

Destroys the TQMutexLocker and unlocks the mutex which was locked +in the constructor. +

See also TQMutexLocker::TQMutexLocker() and TQMutex::unlock(). + +

TQMutex * TQMutexLocker::mutex () const +

+ +

Returns a pointer to the mutex which was locked in the +constructor. +

See also TQMutexLocker::TQMutexLocker(). + + +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1