CopperSpice API  1.7.4
QMutexLocker Class Reference

Simplifies locking and unlocking mutexes. More...

Public Methods

 QMutexLocker (QMutex *mutex)
 
 ~QMutexLocker () = default
 
void lock ()
 
QMutexmutex () const
 
void relock ()
 
void unlock ()
 

Detailed Description

The QMutexLocker class simplifies locking and unlocking mutexes. Locking and unlocking a QMutex manually in complex functions or in exception handling code is error prone and can be difficult to debug. QMutexLocker can be used in such situations to ensure the state of the mutex is always well defined.

The mutex will be locked when QMutexLocker is created. You can unlock and relock the mutex with unlock() and relock(). If locked, the mutex will be unlocked when the QMutexLocker is destroyed.

The QRecursiveMutexLocker class provides the equivalent functionality for code which uses a recursive mutex.

Examples

In this example the function locks a QMutex at the beginning and unlocks the mutex at all the exit points.

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

Using QMutexLocker will simplify the code and improves readable. The code below has been modified to use QMutexLocker. In this new code the mutex will always be unlocked when the QMutexLocker object is destroyed. QMutexLocker is also useful for code which might throw or catch exception.

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

QMutexLocker provides a mutex() method which returns the mutex originally passed in the constructor. This is useful for code that needs access to the mutex, such as QWaitCondition::wait().

class WaitForReady
{
public:
WaitForReady(QWaitCondition *waitCondition, QMutex *mutex)
: m_locker(mutex)
{
}
void wait()
{
while (true) {
// unlocks the given mutex, puts current thread to sleep
// waits for another thread to call m_condition->wakeOne() or m_condition->wakeAll()
m_condition->wait(m_locker.mutex());
// current thread woke up
break;
}
}
private:
QMutexLocker m_locker;
QWaitCondition *m_condition;
};
See also
QMutex, QReadLocker, QRecursiveMutex, QRecursiveMutexLocker, QWriteLocker

Constructor & Destructor Documentation

QMutexLocker::QMutexLocker ( QMutex mutex)
inlineexplicit

Constructs a QMutexLocker and locks mutex. The mutex will be unlocked when the QMutexLocker is destroyed. If mutex is a nullptr QMutexLocker does nothing.

QMutexLocker::~QMutexLocker ( )
default

Destroys the QMutexLocker and unlocks the mutex that was locked in the constructor.

Method Documentation

void QMutexLocker::lock ( )
inline

Locks the mutex passed in the constructor.

See also
relock(), unlock()
QMutex * QMutexLocker::mutex ( ) const
inline

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

void QMutexLocker::relock ( )
inline

Equivalent to calling lock().

void QMutexLocker::unlock ( )
inline

Unlocks this mutex passed in the constructor.

See also
lock(), relock()