NSRecursiveLock

Inherits from:
Object

Implements:
NSLocking

Package:
com.webobjects.foundation

Class Description

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 message in the example above.

The NSRecursiveLock object 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 the NSLock and NSMultiReaderLock class descriptions for more information.

Method Types

Constructors

NSRecursiveLock

Instance methods

lock
tryLock
lockBeforeDate
recursionCount
toString
unlock

Constructors

NSRecursiveLock

public NSRecursiveLock()

Creates an NSRecursiveLock.

Instance Methods

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.

lockBeforeDate

public boolean lockBeforeDate(NSTimestamp timestamp)

This method is deprecated. Use tryLock(NSTimestamp timestamp) instead.

recursionCount

public synchronized long recursionCount()

Returns the receiver's recursion count (the number of unlocks needed to return the lock) if the current thread owns the lock. If the current thread is not the owner of the lock, returns zero.

toString

public String toString()

Returns a string representation of the receiver 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 true. If the current thread owns the lock, increments the recursion count and returns with a value of true. If the another thread owns the lock, returns false immediately.

public boolean tryLock(long msec)

Attempts to acquire a lock for msec milliseconds. If the current thread owns the lock, increments the recursion count and returns true. Otherwise, the thread is blocked until the receiver acquires the lock or msec milliseconds have passed. Returns true if the lock is acquired within this time limit. Returns false if the time limit expires before a lock can be acquired.

public boolean tryLock(NSTimestamp timestamp)

Attempts to acquire a lock until the time specified by timestamp. If the current thread owns the lock, increments the recursion count and returns true. Otherwise, the thread is blocked until the receiver acquires the lock or timestamp is reached. Returns true if the lock is acquired within this time limit. Returns false if the time limit expires before a lock can be acquired.

unlock

public synchronized void unlock()

public synchronized void unlock(long levels)

Decrements the recursion count by levels (decrements the recursion count by one in the no-argument version). If the resulting recursion level is zero, returns the lock. This method throws an Error if the thread that invokes it is not the lock's owner. Invoking this method when the lock count is zero does nothing.