Loading...
Searching...
No Matches
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 Functions

| constructor (Mutex mutex)
| Creates the AutoLock object based on the Mutex argument passed and immediately calls Mutex::lock()
| copy ()
| Throws an exception; objects of this class cannot be copied.
| destructor ()
| Calls Mutex::unlock() on the saved Mutex object and destroys the AutoLock object.
nothing | lock ()
| Attempts to relock the Mutex object being managed.
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.
nothing | unlock ()
| Unlocks the Mutex object being managed; wakes up one thread if any threads are blocked on this lock.

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