Qore Programming Language Reference Manual  0.8.12.11
 All Classes Namespaces Functions Variables Groups Pages
Qore::Thread::AutoLock Class Reference

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

Public Member Functions

 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:

1 our Mutex mutex();
2 
3 sub check_error(error) {
4  # note that the Mutex is acquired in the AutoLock constructor, and
5  # the Mutex will be released as soon as the block is exited below.
6  # (with either the throw statement or the return statement)
7  AutoLock al(mutex);
8  if (error)
9  throw "ERROR", "sorry, an error happened";
10 
11  return "OK";
12 }

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

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:
1 {
2  # when the block exits, the lock is automatically released
3  AutoLock al(mutex);
4 }
Parameters
mutexa Mutex object to lock immediately and hold for the scope of the AutoLock object (unless manually unlocked)
Exceptions
LOCK-ERRORlock called twice in the same thread, Mutex object has already been deleted in another thread, etc
THREAD-DEADLOCKa deadlock was detected while trying to acquire the lock
Qore::Thread::AutoLock::copy ( )

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

Exceptions
AUTOLOCK-COPY-ERRORObjects of this class cannot be copied
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:
1 delete al;
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:
1 al.lock();
Exceptions
LOCK-ERRORlock called twice in the same thread, Mutex object has already been deleted in another thread, etc
THREAD-DEADLOCKa deadlock was detected while trying to acquire the lock
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:
1 int i = al.trylock();
Exceptions
LOCK-ERRORobject deleted in another thread, etc
THREAD-DEADLOCKa deadlock was detected while trying to acquire the lock
nothing Qore::Thread::AutoLock::unlock ( )

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

Example:
1 al.unlock();
Exceptions
LOCK-ERRORunlock called by a thread that does not own the lock or the lock is not locked, object deleted in another thread, etc