Note: This class is not available with the PO_NO_THREAD_CLASSES parse option.
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
}
Table 4.775. Mutex Method Overview
Method | Except? | Description |
|---|---|---|
N | Creates the Mutex object. | |
Y | Destroys the Mutex object. | |
N | Creates a new Mutex object, not based on the original. | |
|
| Y | Locks the Mutex object. Blocks if the lock is already held. |
Y | Unlocks the Mutex object. Wakes up one thread if any threads are blocked on this lock. | |
Y | Acquires the lock only if it is not already held. Returns 0 for success (lock acquired) or -1 if the call would block. |
Creates the Mutex object.
my Mutex $mutex();
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.
delete $mutex;
Table 4.776. Exceptions Thrown by Mutex::destructor()
err | desc |
|---|---|
| Object deleted while other threads blocked on it. |
Creates a new Mutex object, not based on the original.
my Mutex $new_mutex = $mutex.copy();
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().
int Mutex::lock(timeout $timeout_ms)
$mutex.lock();
Table 4.777. Arguments for Mutex::lock()
Argument | Description |
|---|---|
| An optional timeout value to wait to acquire the lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.779. Exceptions Thrown by Mutex::lock()
err | desc |
|---|---|
| A deadlock was detected while trying to acquire the lock. |
| lock called twice in the same thread, object deleted in another thread, etc. |
Unlocks the Mutex object. Wakes up one thread if any threads are blocked on this lock.
$mutex.unlock();
Table 4.780. Exceptions Thrown by Mutex::unlock()
err | desc |
|---|---|
| lock not held, lock held by another thread, object deleted in another thread, etc. |
Acquires the lock only if it is not already held; the return value indicates success (0, lock acquired) or failure (-1, lock already held).
my int $i = $mutex.trylock();
Table 4.781. Return Values for Mutex::trylock()
Return Type | Description |
|---|---|
Returns 0 for success (lock acquired) or -1 if the call would block. |