4.26. Thread::Mutex Class

Note: This class is not available with the PO_NO_THREAD_CLASSES parse option.

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
}

Table 4.949. Mutex Method Overview

Method

Except?

Description

Mutex::constructor()

N

Creates the Mutex object.

Mutex::destructor()

Y

Destroys the Mutex object.

Mutex::copy()

N

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

Mutex::lock()

Y

Locks the Mutex object. Blocks if the lock is already held.

Mutex::unlock()

Y

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

Mutex::trylock()

N

Acquires the lock only if it is not already held. Returns 0 for success (lock acquired) or -1 if the call would block.


4.26.1. Mutex::constructor()

Synopsis

Creates the Mutex object.

Usage
new Mutex()
Example
$mutex = new Mutex();

Table 4.950. Arguments for Mutex::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.951. Return Values for Mutex::constructor()

Return Type

Description

Mutex Object

The new object created.


4.26.2. Mutex::destructor()

Synopsis

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.

Usage
delete lvalue
Example
delete $mutex;

Table 4.952. Exceptions Thrown by Mutex::destructor()

err

desc

LOCK-ERROR

Object deleted while other threads blocked on it.


4.26.3. Mutex::copy()

Synopsis

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

Usage
Mutex::copy()
Example
$new_mutex = $mutex.copy();

Table 4.953. Arguments for Mutex::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.954. Return Values for Mutex::copy()

Return Type

Description

Mutex Object

A new Mutex object, not based on the original.


4.26.4. Mutex::lock()

Synopsis

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().

Usage
Mutex::lock([timeout_ms])
Example
$mutex.lock();

Table 4.955. Arguments for Mutex::lock()

Argument

Type

Description

[timeout_ms]

Integer or Relative Date/Time

If an argument is present, it is interpreted as a timeout in milliseconds. Note that it's recommended to use a relative time value (i.e. 250ms) to make the units clear in the source code.


Table 4.956. Return Values for Mutex::lock()

Return Type

Description

Integer

0 for lock acquired, -1 for timeout (only when a timeout argument is passed)


Table 4.957. Exceptions Thrown by Mutex::lock()

err

desc

THREAD-DEADLOCK

A deadlock was detected while trying to acquire the lock.

LOCK-ERROR

lock called twice in the same thread, object deleted in another thread, etc.


4.26.5. Mutex::unlock()

Synopsis

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

Usage
Mutex::unlock()
Example
$mutex.unlock();

Table 4.958. Arguments for Mutex::unlock()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.959. Return Values for Mutex::unlock()

Return Type

Description

n/a

This method return no value.


Table 4.960. Exceptions Thrown by Mutex::unlock()

err

desc

LOCK-ERROR

lock not held, lock held by another thread, object deleted in another thread, etc.


4.26.6. Mutex::trylock()

Synopsis

Acquires the lock only if it is not already held; the return value indicates success (0, lock acquired) or failure (-1, lock already held).

Usage
Mutex::trylock()
Example
$bool = $mutex.trylock();

Table 4.961. Arguments for Mutex::trylock()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.962. Return Values for Mutex::trylock()

Return Type

Description

Integer

Returns 0 for success (lock acquired) or -1 if the call would block.