QMutexLocker(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

✨ QMutexLocker ✨

okay bestie, we're doing QMutexLocker from the 3qt manuals today and honestly? it's giving guardian angel for your mutexes. 🫶

💖 NAME 💖

QMutexLocker — Simplifies locking and unlocking QMutexes

🌸 SYNOPSIS 🌸

All the functions in this class are thread-safe when Qt is built with thread support. (and yeah, the original literally trails off with a stray </p> right there, no cap — we love a relic 💀)

#include <qmutex.h>

👑 Public Members

  • QMutexLocker ( QMutex * mutex )
  • ~QMutexLocker ()
  • QMutex * mutex () const

🦋 DESCRIPTION 🦋

The QMutexLocker class simplifies locking and unlocking QMutexes.

So the whole point of QMutexLocker is to make QMutex locking and unlocking not a whole ordeal. Locking and unlocking a QMutex inside complex functions and statements, or in exception handling code, is error prone and difficult to debug — like, genuinely a nightmare. QMutexLocker is the one you call in those situations so the state of the mutex stays well defined and is always locked and unlocked properly. periodt. 💅

QMutexLocker should be created within a function where a QMutex needs to be locked. The mutex gets locked the moment the QMutexLocker is created, and unlocked when the QMutexLocker is destroyed. automatic. no notes. ✨

For example, this complex function locks a QMutex 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. 🫠 lowkey terrifying.

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

int complexFunction( int flag )
{
    QMutexLocker 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 QMutexLocker 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. see how much cleaner?? ate. 🎀

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

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

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

See also QMutex, QWaitCondition, Environment Classes, and Threading. 🧚

🎀 MEMBER FUNCTION DOCUMENTATION 🎀

QMutexLocker::QMutexLocker ( QMutex * mutex )

Constructs a QMutexLocker and locks mutex. The mutex will be unlocked when the QMutexLocker is destroyed. If mutex is zero, QMutexLocker does nothing. (zero? it just vibes. does not participate. 🙈)

See also QMutex::lock().

QMutexLocker::~QMutexLocker ()

Destroys the QMutexLocker and unlocks the mutex which was locked in the constructor. the cleanup queen 👑

See also QMutexLocker::QMutexLocker() and QMutex::unlock().

QMutex * QMutexLocker::mutex () const

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

See also QMutexLocker::QMutexLocker().

🌈 SEE ALSO 🌈

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

⭐ AUTHOR ⭐

Generated automatically from the source code. (not me though, i'm typing this with my whole chest 💅)

💀 BUGS 💀

If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you. 🫶

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech. no cap, it's a little unofficial treat just for us.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qmutexlocker.3qt) and the Qt version (3.3.8).

and that's the whole page, bestie — brought to you by Trolltech AS, dated 2 February 2007, filed under QMutexLocker(3qt). go lock something responsibly. 🔥👑🌸

📦 where this page comes from