Qore Programming Language Reference Manual: Qore::Thread::AutoLock Class Reference

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
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:

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)
my 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

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
  my 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

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

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;

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

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:
  my 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

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