Qore::Thread::Mutex Class Reference

A class providing an implementation for a simple thread lock. More...

Inheritance diagram for Qore::Thread::Mutex:
[legend]

## Public Member Functions

| constructor ()
| Creates the Mutex object. More...
| copy ()
| Creates a new Mutex object, not based on the original. More...
| destructor ()
| Destroys the object. More...
nothing | lock ()
| Locks the Mutex object; blocks if the lock is already held. More...
int | lock (timeout timeout_ms)
| Locks the Mutex object; blocks if the lock is already held. More...
int | trylock ()
| 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; wakes up one thread if any threads are blocked on this lock. More...
Public Member Functions inherited from Qore::Thread::AbstractSmartLock
| constructor ()
| Throws an exception if called directly; this class can only be instantiated by builtin subclasses. More...
string | getName ()
| Returns the name of the threading class directly inheriting this class. More...
bool | lockOwner ()
| Returns True if the calling thread owns the lock, False if not. More...
int | lockTID ()
| Returns the TID of the thread owning the lock or -1 if the lock is currently not acquired. More...

## Detailed Description

A class providing an implementation for a simple thread lock.

Restrictions:
  Qore::PO_NO_THREAD_CLASSES

Overview
  This class inherits AbstractSmartLock, so it can be used by Condition objects.
  The Mutex class implements a mutual-exclusion lock for thread locking. Like all Qore thread primitives, objects of this class participate in deadlock detection and throw exceptions when threading errors occur (ex: unlocking a Mutex object locked by another thread, etc). See individual methods for more information on exceptions thrown.
  See the AutoLock class for a class that assists in exception-safe Mutex locking.
  Additionally, the on_exit statement can provide exception-safe unlocking at the lexical block level for Mutex objects as in the following example:
  {
  m.lock();
  on_exit
  m.unlock();
  # ... when this block exits the lock will be released, even in the
  # case of return statements or exceptions
  }

Thread Resource Handling
  The Mutex class manages the lock as a thread resource; if the lock is not released when the thread exits (or when Qore::throw_thread_resource_exceptions() or Qore::throw_thread_resource_exceptions_to_mark() is called), the lock is released automatically and a `LOCK-ERROR` exception is thrown describing the situation.
  Being an builtin class, the Mutex class does not inherit AbstractThreadResource explicitly as a part of the exported API, and the internal AbstractThreadResource::cleanup() method cannot be overridden or suppressed.

Note
  This class is not available with the PO_NO_THREAD_CLASSES parse option

## Member Function Documentation

## constructor()

Qore::Thread::Mutex::constructor | ( |  | ) |

Creates the Mutex object.

Example:
  Mutex mutex();

## copy()

Qore::Thread::Mutex::copy | ( |  | ) |

Creates a new Mutex object, not based on the original.

Example:
  Mutex nm = m.copy();

## destructor()

Qore::Thread::Mutex::destructor | ( |  | ) |

Destroys the object.

Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.

Example:
  delete mutex;

Exceptions

  LOCK-ERROR | Object deleted while other threads blocked on it

## lock() [1/2]

nothing Qore::Thread::Mutex::lock | ( |  | ) |

Locks the Mutex object; blocks if the lock is already held.

To release the Mutex, use Mutex::unlock()

Example:
  mutex.lock();

Exceptions

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

## lock() [2/2]

int Qore::Thread::Mutex::lock | ( | timeout | timeout_ms | ) |

Locks the Mutex object; blocks if the lock is already held.

An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear

To release the Mutex, use Mutex::unlock()

Example:
  if (mutex.lock(1250ms))
  throw "TIMEOUT-ERROR", "lock acquisition timed out after 1.25s";

Parameters

  timeout_ms | a timeout value to wait to acquire the lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally (with a resolution of milliseconds)

Returns
  returns -1 for error, 0 for success

Exceptions

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

## trylock()

int Qore::Thread::Mutex::trylock | ( |  | ) |

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)

Example:
  int i = mutex.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::Mutex::unlock | ( |  | ) |

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

Example:
  mutex.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