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 |
---|---|---|
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. | |
N | 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.
new Mutex()
$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. |
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 lvalue
delete $mutex;
Table 4.952. 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.
Mutex::copy()
$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. |
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().
Mutex::lock([timeout_ms]
)
$mutex.lock();
Table 4.955. Arguments for Mutex::lock()
Argument | Type | Description |
---|---|---|
| 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. |
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 |
---|---|
| 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()
$mutex.unlock();
Table 4.958. Arguments for Mutex::unlock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.960. 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).
Mutex::trylock()
$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. |