RWTRecursiveLock< Mutex > Class Template Reference

Supports recursive acquisition of a mutex. More...

#include <rw/sync/RWTRecursiveLock.h>

Inheritance diagram for RWTRecursiveLock< Mutex >:

Public Types
typedef RWTLockGuard< RWTRecursiveLock< Mutex > >	LockGuard
typedef RWTReadLockGuard< RWTRecursiveLock< Mutex > >	ReadLockGuard
typedef RWTReadUnlockGuard< RWTRecursiveLock< Mutex > >	ReadUnlockGuard
typedef RWTTryLockGuard< RWTRecursiveLock< Mutex > >	TryLockGuard
typedef RWTTryReadLockGuard< RWTRecursiveLock< Mutex > >	TryReadLockGuard
typedef RWTTryWriteLockGuard< RWTRecursiveLock< Mutex > >	TryWriteLockGuard
typedef RWTUnlockGuard< RWTRecursiveLock< Mutex > >	UnlockGuard
typedef RWTWriteLockGuard< RWTRecursiveLock< Mutex > >	WriteLockGuard
typedef RWTWriteUnlockGuard< RWTRecursiveLock< Mutex > >	WriteUnlockGuard

Public Member Functions
	RWTRecursiveLock (RWCancellationState state=0)
	~RWTRecursiveLock (void)
RWWaitStatus	acquire (unsigned long milliseconds)
void	acquire (void)
RWWaitStatus	acquireRead (unsigned long milliseconds)
void	acquireRead (void)
RWWaitStatus	acquireWrite (unsigned long milliseconds)
void	acquireWrite (void)
bool	isAcquired (void) const
void	release (void)
bool	tryAcquire (void)
bool	tryAcquireRead (void)
bool	tryAcquireWrite (void)
Public Member Functions inherited from RWSynchObject
void	disableCancellation ()
void	enableCancellation (RWCancellationState)
bool	isCancellationEnabled () const
void	setCancellation (RWCancellationState)

Private Member Functions
	RWTRecursiveLock (const RWTRecursiveLock< Mutex > &second)
RWTRecursiveLock< Mutex > &	operator= (const RWTRecursiveLock< Mutex > &second)

Additional Inherited Members
Protected Member Functions inherited from RWSynchObject
	RWSynchObject (const RWSynchObject &second)
	RWSynchObject (RWCancellationState state=0)
	RWSynchObject (RWStaticCtor)
RWSynchObject &	operator= (const RWSynchObject &second)
void	testCancellation ()
Related Symbols inherited from RWSynchObject
#define	RW_CANCELLATION_DISABLED
#define	RW_CANCELLATION_ENABLED
typedef void(*	RWCancellationState) ()
void	rwServiceCancellation (void)

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 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.

Example

#include <rw/sync/RWMutexLock.h>
#include <rw/sync/RWTRecursiveLock.h>
 
void func1();
void func2();
 
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

LockGuard

template<class Mutex >

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

Predefined type for compatible guard.

ReadLockGuard

template<class Mutex >

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

Predefined type for compatible guard.

ReadUnlockGuard

template<class Mutex >

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

Predefined type for compatible guard.

TryLockGuard

template<class Mutex >

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

Predefined type for compatible guard.

TryReadLockGuard

template<class Mutex >

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

Predefined type for compatible guard.

TryWriteLockGuard

template<class Mutex >

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

Predefined type for compatible guard.

UnlockGuard

template<class Mutex >

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

Predefined type for compatible guard.

WriteLockGuard

template<class Mutex >

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

Predefined type for compatible guard.

WriteUnlockGuard

template<class Mutex >

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

Predefined type for compatible guard.

Constructor & Destructor Documentation

RWTRecursiveLock() [1/2]

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.

~RWTRecursiveLock()

template<class Mutex >

RWTRecursiveLock< Mutex >::~RWTRecursiveLock ( void )

inline

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

RWTRecursiveLock() [2/2]

template<class Mutex >

RWTRecursiveLock< Mutex >::RWTRecursiveLock ( const RWTRecursiveLock< Mutex > & second )

private

Copy construction prohibited.

Member Function Documentation

acquire() [1/2]

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.

acquire() [2/2]

template<class Mutex >

void RWTRecursiveLock< Mutex >::acquire

(

void

)

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.

acquireRead() [1/2]

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.

acquireRead() [2/2]

template<class Mutex >

void RWTRecursiveLock< Mutex >::acquireRead ( void )

inline

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

acquireWrite() [1/2]

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.

acquireWrite() [2/2]

template<class Mutex >

void RWTRecursiveLock< Mutex >::acquireWrite ( void )

inline

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

isAcquired()

template<class Mutex >

bool RWTRecursiveLock< Mutex >::isAcquired

(

void

)

const

Determines whether the calling thread currently owns the mutex.

Condition:

Available only from the debug version of the Threads Module.

operator=()

template<class Mutex >

RWTRecursiveLock< Mutex > & RWTRecursiveLock< Mutex >::operator= ( const RWTRecursiveLock< Mutex > & second )

private

Assignment prohibited.

release()

template<class Mutex >

void RWTRecursiveLock< Mutex >::release

(

void

)

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.

tryAcquire()

template<class Mutex >

bool RWTRecursiveLock< Mutex >::tryAcquire

(

void

)

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.

tryAcquireRead()

template<class Mutex >

bool RWTRecursiveLock< Mutex >::tryAcquireRead ( void )

inline

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

tryAcquireWrite()

template<class Mutex >

bool RWTRecursiveLock< Mutex >::tryAcquireWrite ( void )

inline

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