Qore::Thread::Mutex Class Reference

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

#include <QC_Mutex.dox.h>

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