org.sape.carbon.core.util.thread
Class ReentrantWriterPreferenceReadWriteLock

java.lang.Object
  |
  +--org.sape.carbon.core.util.thread.WriterPreferenceReadWriteLock
        |
        +--org.sape.carbon.core.util.thread.ReentrantWriterPreferenceReadWriteLock

All Implemented Interfaces:

ReadWriteLock

public class ReentrantWriterPreferenceReadWriteLock

extends WriterPreferenceReadWriteLock

A writer-preference ReadWriteLock that allows both readers and writers to reacquire read or write locks in the style of a ReentrantLock. Readers are not allowed until all write locks held by the writing thread have been released. Among other applications, reentrancy can be useful when write locks are held during calls or callbacks to methods that perform reads under read locks.

Sample usage. Here is a code sketch showing how to exploit reentrancy to perform lock downgrading after updating a cache:

 class CachedData {
   Object data;
   volatile boolean cacheValid;
   ReentrantWriterPreferenceReadWriteLock rwl = ...

   void processCachedData() {
     rwl.readLock().acquire();
     if (!cacheValid) {

        // upgrade lock:
        rwl.readLock().release();   // must release first to obtain writelock
        rwl.writeLock().acquire();
        if (!cacheValid) { // recheck
          data = ...
          cacheValid = true;
        }
        // downgrade lock
        rwl.readLock().acquire();  // reacquire read without giving up lock
        rwl.writeLock().release(); // release write, still hold read
     }

     use(data);
     rwl.readLock().release();
   }
 }
 

[ Introduction to this package. ]

Since:

carbon 2.0

Version:

$Revision: 1.3 $($Author: dvoet $ / $Date: 2003/05/05 21:21:24 $)

Author:

Doug Lea

Nested Class Summary

Nested classes inherited from class org.sape.carbon.core.util.thread.WriterPreferenceReadWriteLock

WriterPreferenceReadWriteLock.ReaderLock, WriterPreferenceReadWriteLock.Signaller, WriterPreferenceReadWriteLock.WriterLock

Field Summary

protected static Integer	IONE cache/reuse the special Integer value one to speed up readlocks
protected HashMap	readers_ Number of acquires on read lock by any reader thread
protected long	writeHolds_ Number of acquires on write lock by activeWriter_ thread

Fields inherited from class org.sape.carbon.core.util.thread.WriterPreferenceReadWriteLock

activeReaders_, activeWriter_, readerLock_, waitingReaders_, waitingWriters_, writerLock_

Constructor Summary

ReentrantWriterPreferenceReadWriteLock()

Method Summary

protected boolean	allowReader() Override this method to change to reader preference
protected WriterPreferenceReadWriteLock.Signaller	endRead() Called upon termination of a read.
protected WriterPreferenceReadWriteLock.Signaller	endWrite() Called upon termination of a write.
protected boolean	startRead()
protected boolean	startWrite()

Methods inherited from class org.sape.carbon.core.util.thread.WriterPreferenceReadWriteLock

cancelledWaitingReader, cancelledWaitingWriter, readLock, startReadFromNewReader, startReadFromWaitingReader, startWriteFromNewWriter, startWriteFromWaitingWriter, writeLock

Methods inherited from class java.lang.Object

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

Field Detail

writeHolds_

protected long writeHolds_

Number of acquires on write lock by activeWriter_ thread

readers_

protected HashMap readers_

Number of acquires on read lock by any reader thread

IONE

protected static final Integer IONE

cache/reuse the special Integer value one to speed up readlocks

Constructor Detail

ReentrantWriterPreferenceReadWriteLock

public ReentrantWriterPreferenceReadWriteLock()

Method Detail

allowReader

protected boolean allowReader()

Description copied from class: WriterPreferenceReadWriteLock

Override this method to change to reader preference

Overrides:

allowReader in class WriterPreferenceReadWriteLock

startRead

protected boolean startRead()

Overrides:

startRead in class WriterPreferenceReadWriteLock

startWrite

protected boolean startWrite()

Overrides:

startWrite in class WriterPreferenceReadWriteLock

endRead

protected WriterPreferenceReadWriteLock.Signaller endRead()

Description copied from class: WriterPreferenceReadWriteLock

Called upon termination of a read. Returns the object to signal to wake up a waiter, or null if no such

Overrides:

endRead in class WriterPreferenceReadWriteLock

endWrite

protected WriterPreferenceReadWriteLock.Signaller endWrite()

Description copied from class: WriterPreferenceReadWriteLock

Called upon termination of a write. Returns the object to signal to wake up a waiter, or null if no such

Overrides:

endWrite in class WriterPreferenceReadWriteLock