org.jboss.cache.lock
Class ReadWriteLockWithUpgrade

java.lang.Object
  org.jboss.cache.lock.ReadWriteLockWithUpgrade

All Implemented Interfaces:

java.util.concurrent.locks.ReadWriteLock

Direct Known Subclasses:

NonBlockingWriterLock

public class ReadWriteLockWithUpgrade
extends java.lang.Object
implements java.util.concurrent.locks.ReadWriteLock

This class is similar to PreferredWriterReadWriteLock except that the read lock is upgradable to write lock. I.e., when a user calls upgradeLock(), it will release the read lock, wait for all the read locks to clear and obtain a write lock afterwards. In particular, the write lock is obtained with priority to prevent deadlock situation. The current design is based in part from Doug Lea's PreferredWriterReadWriteLock.

Note that the pre-requisite to use upgrade lock is the pre-existing of a read lock. Otherwise, a RuntimeException will be thrown.

Also note that currently lock can only be obtained through attempt api with specified timeout instead acquire is not supported.

Internally, the upgrade is done through a Semaphore where a thread with a higher priority will obtain the write lock first. The following scenarios then can happen:

• If there are multiple read locks granted (and no write lock request in waiting), an upgrade will release one read lock (decrease the counter), bump up upagrade counter, increase the current thread priority, set a thread local as upgrade thread, and place a write lock acquire() call. Upon waken up, it will check if the current thread is an upgrade. If it is, restore the thread priority, and decrease the upgrade counter.
• If there are mutiple write locks request in waiting (and only one read lock granted), decrease the read lock counter, bump up the upgrade counter, and increase the current thread priority. When one of the writer gets wake up, it will first check if upgrade counter is zero. If not, it will first release the semaphore so the upgrade thread can grab it, check the semaphore is gone, do notify, and issue myself another acquire to grab the nextInterceptor available semaphore.

Author:

Ben Wang

Nested Class Summary

protected class	ReadWriteLockWithUpgrade.ReaderLock
protected class	ReadWriteLockWithUpgrade.WriterLock

Field Summary

protected java.lang.Thread	activeWriter_
protected static java.lang.Object	dummy_
protected static org.apache.commons.logging.Log	log_
protected ReadWriteLockWithUpgrade.ReaderLock	readerLock_
protected static java.util.Map<java.util.concurrent.locks.ReadWriteLock,java.lang.Object>	upgraderLocal_
protected ReadWriteLockWithUpgrade.WriterLock	writerLock_

Constructor Summary

ReadWriteLockWithUpgrade()

Method Summary

protected boolean	allowReader() Override this method to change to reader preference *
protected void	cancelledWaitingReader()
protected void	cancelledWaitingWriter()
protected org.jboss.cache.lock.ReadWriteLockWithUpgrade.Signaller	endRead() Called upon termination of a read.
protected org.jboss.cache.lock.ReadWriteLockWithUpgrade.Signaller	endWrite() Called upon termination of a write.
protected java.util.concurrent.locks.Lock	changeLock()
java.util.concurrent.locks.Lock	readLock()
protected boolean	startRead()
protected boolean	startReadFromNewReader()
protected boolean	startReadFromWaitingReader()
protected boolean	startWrite()
protected boolean	startWriteFromNewWriter()
protected boolean	startWriteFromWaitingWriter()
java.lang.String	toString()
java.util.concurrent.locks.Lock	upgradeLockAttempt(long msecs) Attempt to obtain an upgrade to writer lock.
java.util.concurrent.locks.Lock	writeLock()

Methods inherited from class java.lang.Object

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

Field Detail

activeWriter_

protected java.lang.Thread activeWriter_

upgraderLocal_

protected static final java.util.Map<java.util.concurrent.locks.ReadWriteLock,java.lang.Object> upgraderLocal_

dummy_

protected static final java.lang.Object dummy_

readerLock_

protected final ReadWriteLockWithUpgrade.ReaderLock readerLock_

writerLock_

protected final ReadWriteLockWithUpgrade.WriterLock writerLock_

log_

protected static final org.apache.commons.logging.Log log_

Constructor Detail

ReadWriteLockWithUpgrade

public ReadWriteLockWithUpgrade()

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

writeLock

public java.util.concurrent.locks.Lock writeLock()

Specified by:

writeLock in interface java.util.concurrent.locks.ReadWriteLock

readLock

public java.util.concurrent.locks.Lock readLock()

Specified by:

readLock in interface java.util.concurrent.locks.ReadWriteLock

upgradeLockAttempt

public java.util.concurrent.locks.Lock upgradeLockAttempt(long msecs)
                                                   throws UpgradeException

Attempt to obtain an upgrade to writer lock. If successful, the read lock is upgraded to write lock. If fails, the owner retains the read lock.

Parameters:

msecs - Time to wait in millisecons.

Returns:

Sync object. Null if not successful or timeout.

Throws:

UpgradeException

changeLock

protected java.util.concurrent.locks.Lock changeLock()

cancelledWaitingReader

protected void cancelledWaitingReader()

cancelledWaitingWriter

protected void cancelledWaitingWriter()

allowReader

protected boolean allowReader()

Override this method to change to reader preference *

startRead

protected boolean startRead()

startWrite

protected boolean startWrite()

startReadFromNewReader

protected boolean startReadFromNewReader()

startWriteFromNewWriter

protected boolean startWriteFromNewWriter()

startReadFromWaitingReader

protected boolean startReadFromWaitingReader()

startWriteFromWaitingWriter

protected boolean startWriteFromWaitingWriter()

endRead

protected org.jboss.cache.lock.ReadWriteLockWithUpgrade.Signaller endRead()

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

endWrite

protected org.jboss.cache.lock.ReadWriteLockWithUpgrade.Signaller endWrite()

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