com.webobjects.foundation
Class NSMultiReaderLock

java.lang.Object
  com.webobjects.foundation.NSMultiReaderLock

All Implemented Interfaces:

NSLocking

public class NSMultiReaderLock

extends Object

implements NSLocking

The NSMultiReaderLock class provides reader and writer locks. The locks are recursive; a single thread can request a lock many times, but a lock is actually taken only on the first request. Likewise, when a thread indicates it's finished with a lock, it takes an equal number of unlock... invocations to return the lock.

There's no limit on the number of reader locks that a process can take. However, there can only be one writer lock at a time, and a writer lock is not issued until all reader locks are returned. Reader locks aren't issued to new threads when there is a thread waiting for a writer lock, but threads that already have a reader lock can increment their lock count.

NSMultiReaderLock correctly handles promotion of a reader lock to a writer lock, and the extension of a reader lock to the current writer. This prevents a thread from deadlocking on itself when requesting a combination of lock types.

NSMultiReaderLocks are slightly more time-expensive than NSRecursiveLocks because the recursion count has to be stored per-thread, causing each request for a reader lock to incur at least one hash lookup. Writer locks are even more expensive because NSMultiReaderLock must poll the hashtable until all reader locks have been returned before the writer lock can be taken.

See Also:

NSRecursiveLock

Field Summary

Fields inherited from interface com.webobjects.foundation.NSLocking

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

Constructor Summary

NSMultiReaderLock()
Creates an NSMultiReaderLock object.

Method Summary

void	lock() Conformance to NSLocking.
void	lockForReading() Acquires a reader lock for the current thread.
void	lockForWriting() Gets a writer lock for the current thread.
void	retrieveReaderLocks() Reinstates the current thread's reader locks that have been suspended using suspendReaderLocks.
void	suspendReaderLocks() Temporarily relinquishes all of the current thread's reader locks, releasing the lock if all reader locks are unlocked.
String	toString()
boolean	tryLockForReading() There are three ways a thread can immediately obtain a reader lock.
boolean	tryLockForWriting() This method implicitly calls lockForWriting, so unlockForWriting must be called if tryLockForWriting returns true.
void	unlock() Conformance to NSLocking.
void	unlockForReading() Releases a reader lock for the current thread.
void	unlockForWriting() Releases a writer lock for the current thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

NSMultiReaderLock

public NSMultiReaderLock()

Creates an NSMultiReaderLock object.

Method Detail

lock

public void lock()

Conformance to NSLocking.

Specified by:

lock in interface NSLocking

See Also:

NSLocking, lockForWriting()

lockForReading

public void lockForReading()

Acquires a reader lock for the current thread. If the current thread doesn't already have a lock, the method blocks if there are any waiting or active writer locks. If the current thread already has a lock (reader or writer), the lock request count is incremented.

lockForWriting

public void lockForWriting()

Gets a writer lock for the current thread. If the current thread already has one, the lock request count is incremented, but a new lock is not taken. If the requesting thread has outstanding reader locks, they are temporarily dropped until the writer lock is returned. If other threads have outstanding reader locks, this method blocks until all reader locks have been freed.

retrieveReaderLocks

public void retrieveReaderLocks()

Reinstates the current thread's reader locks that have been suspended using suspendReaderLocks.

See Also:

suspendReaderLocks()

suspendReaderLocks

public void suspendReaderLocks()

Temporarily relinquishes all of the current thread's reader locks, releasing the lock if all reader locks are unlocked. To reinstate the current thread's suspended reader locks, use the retrieveReaderLocks method.

See Also:

retrieveReaderLocks()

toString

public String toString()

Returns:

a String representation of the receiver containing the current thread name and a table with the names and reader lock counts of all the receiver's threads

tryLockForReading

public boolean tryLockForReading()

There are three ways a thread can immediately obtain a reader lock.

1. There are no outstanding writer locks.
2. The writer lock is held by the current thread.
3. The current thread already has a reader lock.

This method implicitly calls lockForReading, unlockForReading must be called if tryLockForReading returns true.

Returns:

true if the current thread is able to immediately obtain a reader lock

tryLockForWriting

public boolean tryLockForWriting()

This method implicitly calls lockForWriting, so unlockForWriting must be called if tryLockForWriting returns true.

Returns:

true if the current thread is able to immediately obtain a writer lock, else false if another thread already has the lock or is queued to receive it

unlock

public void unlock()

Conformance to NSLocking. This method is equivalent to unlockForWriting.

Specified by:

unlock in interface NSLocking

See Also:

unlockForWriting()

unlockForReading

public void unlockForReading()

Releases a reader lock for the current thread. Each lockForReading message must be paired with an unlockForReading message before the lock is actually released. Invoking this method when the lock count is zero does nothing.

unlockForWriting

public void unlockForWriting()

Releases a writer lock for the current thread. Each lockForWriting message must be paired with an unlockForWriting message before the lock is actually released. When the writer lock is released, it checks to see if the thread previously had any reader locks. If so, the reader lock count is restored. Invoking this method when the lock count is zero does nothing.