The Mutex class is used by TSE3 to ensure thread safety. All potentially contenious TSE3 methods claim a Mutex to prevent TSE3 being entered by multiple threads.
This Mutex class provides a platform independant interface to the underlying mutex implementation (which is accessed through the MutexImpl class interface).
There is a single, global TSE3 Mutex object that is used by the entire library. This is accessed by calling the mutex static member function.
On each different platform supported by TSE3 there will be a specific MutexImpl class.
By default, the TSE3 library is not configured to be thread safe: the default MutexImpl that will be used is the NullMutexImpl. This implementation performs no operations for lock and unlock.
In order to make TSE3 thread safe, you must have an implementation of the MutexImpl class, and pass this to the static setImpl method BEFORE using any of the other TSE3 API. (In fact, you only need set this before the first call to the static mutex method, but most API functions will call this at some time).
A simplification of the Mutex API is provided by the CritSec class. In some cases this is a more convenient interface to use.
See also: MutexImpl, NullMutexImpl, CritSec
| Mutex (MutexImpl *i)
Creates a Mutex object with the specified implementation.
This MutexImpl object is considered to be owned by the Mutex class, and will be deleted when the Mutex is deleted - you need not delete it yourself.
This does imply that there must be a one-to-one relationship between Mutex objects and MutexImpl objects.
A Mutex is created in an unlocked state.
|impl||MutexImpl object to use|
| ~Mutex ()
| void setImpl (MutexImpl *impl)
Sets the MutexImpl class that will be used by the global Mutex object.
It is very important to call this method BEFORE calling mutex to use the global Mutex object. Since most TSE3 API methods call mutex, it is safest to set the MutexImpl before calling any other TSE3 method.
The impl you specify must exist for as long as you use the TSE3 library.
If you do not specify a MutexImpl then a default NullMutexImpl will be used, and TSE3 will not be thread-safe.
You may only call this once: subsequent calls are ignored and the first MutexImpl specified is used.
|impl||MutexImpl to use. This will be deleted by the Mutex class - you may forget about it.|
| Mutex * mutex ()
Provides access to the global Mutex object used to lock the TSE3 library.
The first time this method is called, a Mutex object will be created with the MutexImpl specified by setImpl.
|void lock ()
Locks the Mutex.
If the Mutex is already locked by a different thread, then this thread will block until the previous one unlocks the mutex.
A single thread can lock the mutex multiple times. However, subsequent calls to lock have no effect. There must be the same number of calls to unlock before the Mutex is unlocked, though.
See also: unlock
|void unlock ()
Unlocks the Mutex. To unlock the mutex fully, as many unlocks must be called as locks.
If the Mutex is already unlocked, then nothing will happen.
See also: lock