Qore Programming Language Reference Manual: Qore::Thread::Mutex 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::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

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
}

Note
  This class is not available with the PO_NO_THREAD_CLASSES parse option

## Member Function Documentation

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

Creates the Mutex object.

Example:
  my Mutex $mutex();

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

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

Example:
  my Mutex $nm = $m.copy();

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

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

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

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

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