ReentrantWriterPreferenceReadWriteLock (Castor JavaDoc)

java.lang.Object
- org.castor.core.util.concurrent.WriterPreferenceReadWriteLock
- - org.castor.core.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:: "java.util.concurrent.locks.ReentrantLock in Java 5 or later JavaDoc"

Nested Class Summary
- Nested classes/interfaces inherited from class org.castor.core.util.concurrent.WriterPreferenceReadWriteLock
  WriterPreferenceReadWriteLock.ReaderLock, WriterPreferenceReadWriteLock.Signaller, WriterPreferenceReadWriteLock.WriterLock

Field Summary

Fields
Modifier and Type	Field and Description
`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 org.castor.core.util.concurrent.WriterPreferenceReadWriteLock
activeReaders_, activeWriter_, readerLock_, waitingReaders_, waitingWriters_, writerLock_

Constructor Summary

Constructors
Constructor and Description

ReentrantWriterPreferenceReadWriteLock()

Constructors
Constructor and Description
`ReentrantWriterPreferenceReadWriteLock()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.castor.core.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

Class ReentrantWriterPreferenceReadWriteLock

Nested Class Summary

Nested classes/interfaces inherited from class org.castor.core.util.concurrent.WriterPreferenceReadWriteLock

Field Summary

Fields inherited from class org.castor.core.util.concurrent.WriterPreferenceReadWriteLock

Constructor Summary

Method Summary

Methods inherited from class org.castor.core.util.concurrent.WriterPreferenceReadWriteLock

Methods inherited from class java.lang.Object

Field Detail

writeHolds_

readers_

IONE

Constructor Detail

ReentrantWriterPreferenceReadWriteLock

Method Detail

allowReader

startRead

startWrite

endRead

endWrite