RWTRecursiveLock<Lock>

Module:  Threads   Package:  Synchronization

RWTRecursiveLock<Lock>   RWSynchObject

• Local Index
• Header File
• Description
• Example
• Member Typedefs
• Public Constructors
• Public Destructor
• Public Member Functions
• Private Constructor
• Private Member Operator
• See Also

Members

acquire() acquireRead() acquireWrite() isAcquired() LockGuard

operator ReadLockGuard ReadUnlockGuard release() RWTRecursiveLock()

tryAcquire() tryAcquireRead() tryAcquireWrite() TryLockGuard TryReadLockGuard

TryWriteLockGuard UnlockGuard WriteLockGuard WriteUnlockGuard ~RWTRecursiveLock()

#include <rw/sync/RWTRecursiveLock.h> 

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

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

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;

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.

~RWTRecursiveLock();

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

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

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.

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.

void
acquireRead();

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();

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.

bool
isAcquired() const;

Determines whether the calling thread currently owns the mutex.

---

NOTE -- Only available from the debug version of the module

---

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

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

bool
tryAcquireRead();

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

bool
tryAcquireWrite();

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

RWTRecursiveLock(const RWTRecursiveLock<Lock>& second);

Copy construction prohibited.

RWTRecursiveLock<Lock>&
operator=(const RWTRecursiveLock<Lock>& second);

Assignment prohibited.

RWMutexLock, RWFIFOMutexLock

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.