Qore Programming Language Reference Manual  0.9.1
Qore::Thread::Mutex Class Reference

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

Inheritance diagram for Qore::Thread::Mutex:

Public Member Methods

 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 Methods 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-ERRORObject 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-ERRORlock called twice in the same thread, object deleted in another thread, etc
THREAD-DEADLOCKa 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_msa 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-ERRORlock called twice in the same thread, object deleted in another thread, etc
THREAD-DEADLOCKa 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-ERRORobject deleted in another thread, etc
THREAD-DEADLOCKa 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-ERRORunlock called by a thread that does not own the lock or the lock is not locked, object deleted in another thread, etc