com.webobjects.foundation
Class NSRecursiveLock

java.lang.Object
  com.webobjects.foundation.NSRecursiveLock

All Implemented Interfaces:

NSLocking

public class NSRecursiveLock

extends Object

implements NSLocking

NSRecursiveLock defines a lock that may be acquired multiple times by the same thread without causing a deadlock (a situation where a thread is permanently blocked waiting for itself to relinquish a lock). While the locking thread has one or more locks, all other threads are prevented from accessing the code protected by the lock. Here's an example where a recursive lock functions properly but other lock types would deadlock:

 NSRecursiveLock theLock = new NSRecursiveLock();
 ...
 theLock.lock();
 //lengthy operations involving global data
 theLock.lock(); //possibly invoked in a subroutine
 ...
 theLock.unlock(); //relinquishes most recent lock
 ...
 theLock.unlock(); //relinquishes the first lock
 

Unless theLock was an NSRecursiveLock, a deadlock condition would occur at the second lock invocation in the example above.

An NSRecursiveLock keeps track of the recursion count: the number of lock requests that the owning thread has made and not unlocked. This is also the number of times unlock must be invoked to return the lock. To access the recursion count, use the recursionCount method.

The NSLock, NSMultiReaderLock, and NSRecursiveLock classes all adopt the NSLocking protocol and offer various additional features and performance characteristics.

See Also:

NSLock, NSMultiReaderLock, recursionCount()

Field Summary

Fields inherited from interface com.webobjects.foundation.NSLocking

OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear

Constructor Summary

NSRecursiveLock()
Creates an NSRecursiveLock.

Method Summary

void	lock() Conformance to NSLocking.
boolean	lockBeforeDate(NSTimestamp timestamp) Deprecated. Use tryLock(NSTimestamp)
long	recursionCount() Gets this NSRecursiveLock object's recursion count.
String	toString()
boolean	tryLock() Attempts to acquire a lock.
boolean	tryLock(long msecs) Attempts to acquire a lock for msecs milliseconds.
boolean	tryLock(NSTimestamp timestamp) Attempts to acquire a lock until a specific time timestamp is reached.
void	unlock() Attemps to relinquish a previously acquired lock by decreasing the recursion count by 1.
void	unlock(long n) Attemps to relinquish a previously acquired lock by decreasing the recursion count by n.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NSRecursiveLock

public NSRecursiveLock()

Creates an NSRecursiveLock.

Method Detail

lock

public void lock()

Conformance to NSLocking. See the method description of lock in the interface description for NSLocking. If the current thread already owns the lock, this method increments the recursion count.

Specified by:

lock in interface NSLocking

lockBeforeDate

public boolean lockBeforeDate(NSTimestamp timestamp)

Deprecated. Use tryLock(NSTimestamp)

Parameters:

timestamp - n/a

Returns:

n/a

recursionCount

public long recursionCount()

Gets this NSRecursiveLock object's recursion count.

Returns:

the recursion count; as well, 0 if the current thread is not the owner of this lock

toString

public String toString()

Returns:

a String representing this NSRecursiveLock object that includes the thread that owns it and its recursion count

tryLock

public boolean tryLock()

Attempts to acquire a lock. If the lock is not already taken by another thread, acquires the lock, sets the recursion count to 1 and returns. If the current thread owns the lock, adds 1 to the recursion count and returns.

Returns:

true if the lock was acquired; false if another thread owns the lock

tryLock

public boolean tryLock(long msecs)

Attempts to acquire a lock for msecs milliseconds. If the current thread owns the lock, adds 1 to the recursion count and returns. Otherwise, the thread is blocked until this NSRecursiveLock acquires the lock or msecs milliseconds have passed.

Parameters:

msecs - time limit within which the lock has to be acquired

Returns:

true if the lock is acquired within this time limit; false if the time limit expires before a lock can be acquired

tryLock

public boolean tryLock(NSTimestamp timestamp)

Attempts to acquire a lock until a specific time timestamp is reached. If the current thread owns the lock, adds 1 to the recursion count and returns. Otherwise, the thread is blocked until this NSRecursiveLock acquires the lock or timestamp is reached.

Parameters:

timestamp - input time within which lock must be acquired

Returns:

true if the lock is acquired before timestamp is reached; false otherwise

unlock

public void unlock()

Attemps to relinquish a previously acquired lock by decreasing the recursion count by 1. When the recursion count is 0, this lock is finally released so that other threads waiting can acquire a lock.

Specified by:

unlock in interface NSLocking

Throws:

IllegalStateException - if the invoking thread is not the lock's owner or if no lock has actually been acquired

See Also:

lock()

unlock

public void unlock(long n)

Attemps to relinquish a previously acquired lock by decreasing the recursion count by n. When the recursion count is 0, this lock is finally released so that other threads waiting can acquire a lock.

Parameters:

n - amount to decrease the recursion count by

Throws:

IllegalStateException - if the invoking thread is not the lock's owner, n is a negative number or n is greater than the number of time lock() was called

See Also:

lock()