Qore Programming Language Reference Manual: Qore::Thread::Mutex Class Reference (original) (raw)
A class providing an implementation for a simple thread lock. More...
#include <[QC_Mutex.dox.h](%5Fq%5Fc%5F%5F%5Fmutex%5F8dox%5F8h%5Fsource.html)>
| 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... | |
A class providing an implementation for a simple thread lock.
Restrictions:
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();
}
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
◆ constructor()
| Qore::Thread::Mutex::constructor | ( | ) |
|---|
Creates the Mutex object.
Example:
◆ copy()
| Qore::Thread::Mutex::copy | ( | ) |
|---|
Creates a new Mutex object, not based on the original.
Example:
◆ 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:
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:
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:
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:
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 |
|---|