RWTRecursiveLock< Mutex > Class Template Reference
[Synchronization]

Supports recursive acquisition of a mutex. More...

#include <rw/sync/RWTRecursiveLock.h>

Inheritance diagram for RWTRecursiveLock< Mutex >:

List of all members.

Public Types
typedef RWTLockGuard < RWTRecursiveLock< Mutex > >	LockGuard
typedef RWTReadLockGuard < RWTRecursiveLock< Mutex > >	ReadLockGuard
typedef RWTWriteLockGuard < RWTRecursiveLock< Mutex > >	WriteLockGuard
typedef RWTTryLockGuard < RWTRecursiveLock< Mutex > >	TryLockGuard
typedef RWTTryReadLockGuard < RWTRecursiveLock< Mutex > >	TryReadLockGuard
typedef RWTTryWriteLockGuard < RWTRecursiveLock< Mutex > >	TryWriteLockGuard
typedef RWTUnlockGuard < RWTRecursiveLock< Mutex > >	UnlockGuard
typedef RWTReadUnlockGuard < RWTRecursiveLock< Mutex > >	ReadUnlockGuard
typedef RWTWriteUnlockGuard < RWTRecursiveLock< Mutex > >	WriteUnlockGuard
Public Member Functions
	RWTRecursiveLock (RWCancellationState state=0)
	~RWTRecursiveLock ()
void	acquire ()
RWWaitStatus	acquire (unsigned long milliseconds)
void	acquireRead ()
RWWaitStatus	acquireRead (unsigned long milliseconds)
void	acquireWrite ()
RWWaitStatus	acquireWrite (unsigned long milliseconds)
bool	isAcquired () const
void	release ()
bool	tryAcquire ()
bool	tryAcquireRead ()
bool	tryAcquireWrite ()
Private Member Functions
	RWTRecursiveLock (const RWTRecursiveLock< Mutex > &second)
RWTRecursiveLock< Mutex > &	operator= (const RWTRecursiveLock< Mutex > &second)

---

Detailed Description

template<class Mutex>
class RWTRecursiveLock< Mutex >

The RWMutexLock and RWFIFOMutexLock classes do not allow a thread to acquire the mutex if it already owns it. Attempts to do so result in an assertion and abort in the debug version of the module, and may result in deadlock in the release version.

RWTRecursiveLock<Lock> can be used to add recursive acquisition semantics to an existing mutex class such as RWMutexLock or RWFIFOMutexLock.

This class allows the thread that owns a mutex to reacquire the mutex any number of times before ever releasing it. For each acquisition, however, the thread must release the mutex the same number of times before the resource can become available to another thread.

Examples

 #include <rw/sync/RWMutexLock.h>
 #include <rw/sync/RWTRecursiveLock.h>

 RWTRecursiveLock<RWMutexLock> lock;
 // For this example, assume that the lock is first acquired
 // in func1():
 void func1()
 {
   lock.acquire();  // acquire mutex and set count set to 1
   // critical section
   func2();
   lock.release();  // decrement count to 0 and release
                    // underlying mutex
 }
 void func2()
 {
   lock.acquire();  // OK if called from func1(),
                    // increment count to 2
   // critical section
   lock.release();  // decrement count to 1,
                    // thread still owns mutex
 }

See also:

RWMutexLock RWFIFOMutexLock

---

Member Typedef Documentation

template<class Mutex>

typedef RWTLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::LockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTReadLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::ReadLockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTReadUnlockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::ReadUnlockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTTryLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::TryLockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTTryReadLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::TryReadLockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTTryWriteLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::TryWriteLockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTUnlockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::UnlockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTWriteLockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::WriteLockGuard

Predefined type for compatible guard.

template<class Mutex>

typedef RWTWriteUnlockGuard< RWTRecursiveLock< Mutex > > RWTRecursiveLock< Mutex >::WriteUnlockGuard

Predefined type for compatible guard.

---

Constructor & Destructor Documentation

template<class Mutex>

RWTRecursiveLock< Mutex >::RWTRecursiveLock

(

RWCancellationState

state = 0

)

Creates and initializes an RWTRecursiveLock. The thread cancellation state of the object is initialized to state. Possible exceptions include RWTHRResourceLimit and RWTHRInternalError.

template<class Mutex >

RWTRecursiveLock< Mutex >::~RWTRecursiveLock

(

)

[inline]

Recovers the system resource used to implement the RWTRecursiveLock. Possible exceptions include RWTHRInternalError.

template<class Mutex>

RWTRecursiveLock< Mutex >::RWTRecursiveLock

(

const RWTRecursiveLock< Mutex > &

second

)

[private]

Copy construction prohibited.

---

Member Function Documentation

template<class Mutex>

RWWaitStatus RWTRecursiveLock< Mutex >::acquire

(

unsigned long

milliseconds

)

Acquires the recursive lock, incrementing the nesting level for each time the lock owner calls this method, but timing out if forced to wait for the mutex longer than the specified number of milliseconds. If the call times out, the function returns RW_THR_TIMEOUT.

This function will throw an RWCancellation object if the mutex has cancellation detection enabled and a runnable containing the calling thread has been canceled. Other possible exceptions include RWTHRInternalError.

template<class Mutex>

void RWTRecursiveLock< Mutex >::acquire

(

)

Acquires the recursive lock, incrementing the nesting level for each time the lock owner calls this method.

This function will throw an RWCancellation object if the mutex has cancellation detection enabled and a runnable containing the calling thread has been canceled. Other possible exceptions include RWTHRInternalError.

template<class Mutex >

RWWaitStatus RWTRecursiveLock< Mutex >::acquireRead

(

unsigned long

milliseconds

)

[inline]

Calls acquire(milliseconds) . Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex >

void RWTRecursiveLock< Mutex >::acquireRead

(

)

[inline]

Calls acquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex >

RWWaitStatus RWTRecursiveLock< Mutex >::acquireWrite

(

unsigned long

milliseconds

)

[inline]

Calls acquire(milliseconds) . Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex >

void RWTRecursiveLock< Mutex >::acquireWrite

(

)

[inline]

Calls acquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex>

bool RWTRecursiveLock< Mutex >::isAcquired

(

)

const

Determines whether the calling thread currently owns the mutex.

Condition:

Only available from the debug version of the Threads Module.

template<class Mutex>

RWTRecursiveLock<Mutex>& RWTRecursiveLock< Mutex >::operator=

(

const RWTRecursiveLock< Mutex > &

second

)

[private]

Assignment prohibited.

template<class Mutex>

void RWTRecursiveLock< Mutex >::release

(

)

Releases the recursive lock, decrementing the nesting level each time the lock owner calls this method, and releasing the actual lock when the level reaches zero. Possible exceptions include RWTHRIllegalUsage and RWTHRInternalError.

template<class Mutex>

bool RWTRecursiveLock< Mutex >::tryAcquire

(

)

Conditionally acquires the recursive lock, incrementing the nesting level for each time the lock owner calls this method. This method returns immediately if the lock is unavailable. Returns true if the lock is successfully acquired. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex >

bool RWTRecursiveLock< Mutex >::tryAcquireRead

(

)

[inline]

Calls tryAcquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

template<class Mutex >

bool RWTRecursiveLock< Mutex >::tryAcquireWrite

(

)

[inline]

Calls tryAcquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.