NSMultiReaderLock

Inherits from:
Object

Implements:
NSLocking

Package:
com.webobjects.foundation

Class Description

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.

Method Types

Constructors

NSMultiReaderLock

Managing reader locks

lockForReading
retrieveReaderLocks
suspendReaderLocks
tryLockForReading
unlockForReading

Managing writer locks

lock
lockForWriting
tryLockForWriting
unlock
unlockForWriting

Methods inherited from Object

toString

Constructors

NSMultiReaderLock

public NSMultiReaderLock()

Creates an NSMultiReaderLock object.

Instance Methods

lock

public void lock()

Conformance to NSLocking. See the method description of lock in the interface description for NSLocking. This method is equivalent to 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.

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.

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

Returns true if the current thread is able to immediately obtain a reader lock. There are three ways this can happen:

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

This method implicitly calls lockForReading, so you must call unlockForReading if tryLockForReading returns true.

tryLockForWriting

public boolean tryLockForWriting()

Returns true if the current thread is able to immediately obtain a writer lock. Returns false if another thread already has the lock or is queued to receive it. This method implicitly calls lockForWriting, so you must call unlockForWriting if tryLockForWriting returns true.

unlock

public void unlock()

Conformance to NSLocking. See the method description of unlock in the interface description for NSLocking. This method is equivalent to 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.