## EDU.oswego.cs.dl.util.concurrent
Class ReentrantWriterPreferenceReadWriteLock

    java.lang.Object
      EDU.oswego.cs.dl.util.concurrent.WriterPreferenceReadWriteLock
          EDU.oswego.cs.dl.util.concurrent.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. ]

See Also:
  `ReentrantLock`

Nested Class Summary

Nested classes/interfaces inherited from class EDU.oswego.cs.dl.util.concurrent.WriterPreferenceReadWriteLock
`WriterPreferenceReadWriteLock.ReaderLock, WriterPreferenceReadWriteLock.Signaller, WriterPreferenceReadWriteLock.WriterLock`

Field Summary
`protected static java.lang.Integer` `IONE` cache/reuse the special Integer value one to speed up readlocks
`protected java.util.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 EDU.oswego.cs.dl.util.concurrent.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 EDU.oswego.cs.dl.util.concurrent.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 java.util.HashMap readers_

  Number of acquires on read lock by any reader thread

### IONE

    protected static final java.lang.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`