RWTRecursiveLock<Lock>


RWTRecursiveLock<Lock>  RWSynchObject

Data Type and Member Function Indexes
Package
Header File
Description
Example
Member Typedefs
Public Constructors
Public Destructor
Public Member Functions
See Also

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Header File

#include <rw/sync/RWTRecursiveLock.h>

Description

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

If you require recursive acquisition semantics for a mutex, you can use the RWTRecursiveLock<Lock> class to add this capability 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 it will become available to another thread.

Example

#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
}

Member Typedefs

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 Constructors

RWTRecursiveLock(RWCancellationState
                 state=RW_CANCELLATION_DISABLED);

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

Public Destructor

~RWTRecursiveLock(void);

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

Public Member Functions

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

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

void
acquireRead(void);

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

RWWaitStatus
acquireRead(unsigned long milliseconds);

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

void
acquireWrite(void);

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

RWWaitStatus
acquireWrite(unsigned long milliseconds);

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

RWBoolean
isAcquired(void) const;

Determines whether the calling thread currently owns the mutex.

NOTE: Only available from the debug version of the library

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

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

RWBoolean
tryAcquireRead(void);

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

RWBoolean
tryAcquireWrite(void);

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