Qore::Thread::AutoLock Class Reference

A helper class for the Mutex class for exception-safe Mutex handling. More...

#include <QC_AutoLock.dox.h>

Public Member Methods
	constructor (Mutex mutex)
	Creates the AutoLock object based on the Mutex argument passed and immediately calls Mutex::lock() More...
	copy ()
	Throws an exception; objects of this class cannot be copied. More...
	destructor ()
	Calls Mutex::unlock() on the saved Mutex object and destroys the AutoLock object. More...
nothing	lock ()
	Attempts to relock the Mutex object being managed. More...
int	trylock ()
	Attempts to relock the Mutex object being managed; acquires the lock only if it is not already held; returns 0 for success (lock acquired) or -1 if the call would block. More...
nothing	unlock ()
	Unlocks the Mutex object being managed; wakes up one thread if any threads are blocked on this lock. More...

Detailed Description

A helper class for the Mutex class for exception-safe Mutex handling.

Restrictions:

Qore::PO_NO_THREAD_CLASSES

AutoLock objects, when used along with a Mutex object, allow Qore programmers to safely acquire and release a Mutex lock, even if exceptions are thrown or return statements are executed in the block where the AutoLock object is created.

AutoLock objects are helper objects that acquire a Mutex for the lifetime of the object.

For this reason, it is only appropriate to assign an AutoLock object to a local variable, so when the local variable goes out of scope, the AutoLock object will be deleted and the Mutex will be automatically released.

For example:

our Mutex mutex();
 
sub check_error(error) {
    # note that the Mutex is acquired in the AutoLock constructor, and
    # the Mutex will be released as soon as the block is exited below.
    # (with either the throw statement or the return statement)
    AutoLock al(mutex);
    if (error)
        throw "ERROR", "sorry, an error happened";
 
    return "OK";
}

The destructor will call Mutex::unlock() only if the current thread owns the lock, so it is safe to unlock the lock manually (or by calling AutoLock::unlock()) while the AutoLock object is in scope.

Note

This class is not available with the PO_NO_THREAD_CLASSES parse option.

Member Function Documentation

constructor()

Qore::Thread::AutoLock::constructor

(

Mutex

mutex

)

Creates the AutoLock object based on the Mutex argument passed and immediately calls Mutex::lock()

The AutoLock object immediately calls Mutex::lock() on the Mutex object passed, and saves it; Mutex::unlock() is called in the destructor if the lock is still held by the current thread.

Example:

{
    # when the block exits, the lock is automatically released
    AutoLock al(mutex);
}

Parameters

mutex

a Mutex object to lock immediately and hold for the scope of the AutoLock object (unless manually unlocked)

Exceptions

LOCK-ERROR	lock called twice in the same thread, Mutex object has already been deleted in another thread, etc
THREAD-DEADLOCK	a deadlock was detected while trying to acquire the lock

copy()

Qore::Thread::AutoLock::copy

(

)

Throws an exception; objects of this class cannot be copied.

Exceptions

AUTOLOCK-COPY-ERROR

Objects of this class cannot be copied

destructor()

Qore::Thread::AutoLock::destructor

(

)

Calls Mutex::unlock() on the saved Mutex object and destroys the AutoLock object.

Mutex::unlock() is only called if the current thread owns the lock

Example:

delete al;

lock()

nothing Qore::Thread::AutoLock::lock

(

)

Attempts to relock the Mutex object being managed.

Do not call this method unless the Mutex object being managed has been unlocked since the constructor

Example:

al.lock();

Exceptions

LOCK-ERROR	lock called twice in the same thread, Mutex object has already been deleted in another thread, etc
THREAD-DEADLOCK	a deadlock was detected while trying to acquire the lock

trylock()

int Qore::Thread::AutoLock::trylock

(

)

Attempts to relock the Mutex object being managed; acquires the lock only if it is not already held; returns 0 for success (lock acquired) or -1 if the call would block.

Returns

0 for success (lock acquired) or -1 if the call would block (lock not acquired because it's held by another thread)

Example:

int i = al.trylock();

Exceptions

LOCK-ERROR	object deleted in another thread, etc
THREAD-DEADLOCK	a deadlock was detected while trying to acquire the lock

unlock()

nothing Qore::Thread::AutoLock::unlock

(

)

Unlocks the Mutex object being managed; wakes up one thread if any threads are blocked on this lock.

Example:

al.unlock();

Exceptions

LOCK-ERROR

unlock called by a thread that does not own the lock or the lock is not locked, object deleted in another thread, etc