SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND


Platform::Thread
Class Mutex

NonCopyableType
   |
   +-ILockable
        |
        +-Mutex

Implemented in:
Platform.Thread.Mutex.h
Direct Known Subclasses:
Monitor

class Mutex:
public ILockable

Represents a mutex synchronization primitive. A mutex provides mutual exclusion among multiple threads accessing a shared resource.

A mutex has acquire-release interface. A thread must acquire a mutex in order to become its owner.

A mutex is recursive, meaning it can be acquired multiple times by the owner, however it must be released the corresponding number of times before other threads can become the owners.

Only one execution thread may be in possession of (i.e. own) a mutex at any given time.

See Also:
Thread::ILockable, Thread::Monitor

Field Summarycollapse
protected Int count
          The number of times the mutex has been acquired by the owner thread.
protected Internals::ThreadSelfType owner
          The owner of the mutex.
protected Internals::ThreadMutexType state
          The state of the mutex.

Constructor Summarycollapse
Mutex()
          Creates a mutex.
~Mutex()
          Destroys this mutex.

Method Summarycollapse
Void acquire()
          Acquires this mutex.
Void acquire(Int spinCount)
          Acquires this mutex.
Void release()
          Releases the mutex.
Bool tryAcquire()
          Attempts to acquire this mutex.
Bool tryAcquire(Int spinCount)
          Attempts to acquire this mutex.

Methods inherited from class ILockablecollapse
acquire, acquire, release, tryAcquire, tryAcquire

 

Field Detail

count

protected Int count

The number of times the mutex has been acquired by the owner thread.


owner

protected Internals::ThreadSelfType owner

The owner of the mutex.


state

protected Internals::ThreadMutexType state

The state of the mutex.

 

Constructor Detail

Mutex[nothrow, inline]

Mutex()

Creates a mutex. The initial state of the created mutex is unacquired, i.e. no thread is in the possession of this mutex.


~Mutex[nothrow, inline]

~Mutex()

Destroys this mutex.

The owner thread must have released the mutex prior to its destruction.

If the owner thread has acquired this mutex multiple times it must release the mutex the corresponding number of times prior to its destruction.

Only the thread that currently owns this mutex may release the mutex.

 

Method Detail

acquire[virtual, nothrow, inline]

Void acquire()

Acquires this mutex. If the acquire operation fails the calling thread will yield and once scheduled to run again will restart the acquire operation. Once an execution thread has acquired the mutex other contending threads will be blocked (waiting) on the mutex until it is released by the owner.

A thread may acquire a mutex multiple times, however it must release the mutex the corresponding number of times before the other contending threads can take possession of the mutex.

See Also:
Thread::yield
Implements:
ILockable::acquire

acquire[virtual, nothrow, inline]

Void acquire(Int spinCount)

Acquires this mutex. If the acquire operation fails the calling thread will repeat the operation the specified number of times (thus polling the mutex without giving up its time quota). If, after the specified number of retries the calling thread still has not succeeded to take ownership of the mutex the thread will yield and once scheduled to run again will restart the acquire operation. Once an execution thread has acquired a mutex other contending threads will be blocked (waiting) on the mutex until it is released by the owner.

A thread may acquire a mutex multiple times, however it must release the mutex the corresponding number of times before the other contending threads can take possession of the mutex.

Parameters:
spinCount - the number of retries before the calling thread yields if it was unable to acquire the mutex
See Also:
Thread::yield
Implements:
ILockable::acquire

release[virtual, nothrow, inline]

Void release()

Releases the mutex. It is an error for a thread to release a mutex it does not own. If a thread has acquired a mutex multiple times it must release the mutex the corresponding number of times before other contending threads can take possession of the mutex.

Implements:
ILockable::release

tryAcquire[virtual, nothrow, inline]

Bool tryAcquire()

Attempts to acquire this mutex. Upon success (if no other thread currently holds this mutex) the mutex ownership is transferred to the calling thread and the method returns True. If the mutex is already held by another thread this method fails returning False.

Returns:
True if the calling thread successfully acquired this mutex, False otherwise
See Also:
Thread::yield
Implements:
ILockable::tryAcquire

tryAcquire[virtual, nothrow, inline]

Bool tryAcquire(Int spinCount)

Attempts to acquire this mutex. If the acquire operation fails the calling thread will repeat the operation the specified number of times (thus polling the mutex without giving up its time quota). If, after the specified number of retries the calling thread succeeds taking the ownership of the mutex, this method returns True. Otherwise this method fails returning False

Parameters:
spinCount - the number of retries to try acquire this mutex
Returns:
True if the calling thread successfully acquired this mutex, False otherwise
See Also:
Thread::yield
Implements:
ILockable::tryAcquire


SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND