Skip navigation links

oracle.javatools.buffer
Class ReadWriteLock

java.lang.Object
oracle.javatools.buffer.ReadWriteLock

public final class ReadWriteLock

extends java.lang.Object

The ReadWriteLock class is a basic implementation of a multiple-reader/single-writer lock. It reference counts by thread to ensure that read locks or write locks can be acquired multiple times by a thread, but that every acquisition by a given thread is balanced by a corresponding release.

Upgrading a lock, that is, acquiring a write lock while holding a read lock on the same thread, has historically been supported by this class. However, two threads trying to upgrade can deadlock. Currently, this class logs a message with level Severe when a lock is upgraded; eventually, it will throw IllegalMonitorStateException

This implementation does not provide a guarantee to prevent writers from being starved.

Nested Class Summary

static class

ReadWriteLock.Options An enumeration of the configuration options for a ReadWriteLock.

Field Summary

static int	DEFAULT_DEADLOCK_INTERVAL
static int	DEFAULT_HISTORY_LIMIT
static java.util.EnumSet<ReadWriteLock.Options>	DEFAULT_OPTIONS
static int	DEFAULT_WAIT_INTERVAL

Constructor Summary

ReadWriteLock()
Creates an anonymous lock.

ReadWriteLock(java.lang.String name)
Creates a named lock.

ReadWriteLock(java.lang.String name, java.util.EnumSet<ReadWriteLock.Options> options, int waitInterval, int deadlockInterval, int historyLimit)
Creates a named lock with specified options.

Method Summary

boolean	addWriteLockRequestListener(WriteLockRequestListener listener) Adds a WriteLockRequestListener on behalf of the current thread.
void	appendSnapshot(java.lang.StringBuilder buffer)
java.lang.String	getName() Gets the name of this lock.
int	getReadHoldCount() Gets the number of times the current thread has taken the read lock for this lock.
int	getWriteHoldCount() Gets the number of times the current thread has taken the write lock for this lock.
boolean	isLockHeld() Gets whether the current thread is holding either a read or write lock for this lock.
boolean	isReadLockHeld() Gets whether the current thread is holding a read lock for this lock.
boolean	isWriteLockHeld() Gets whether the current thread is holding a write lock for this lock.
void	readLock() Acquires a read lock for the current thread, blocking until available.
void	readUnlock() Releases a read lock for the current thread.
static void	registerApiMethod(java.lang.String className, java.lang.String methodName) Registers a method as a lock API method.
void	removeWriteLockRequestListener(WriteLockRequestListener listener) Removes a WriteLockRequestListener.
void	setEventLog(Log log) Sets or clears a logger for lock events.
void	setName(java.lang.String name) Sets the name of this lock.
java.lang.String	toString()
boolean	tryReadLock() Acquires a read lock for the current thread only if possible without blocking the thread; returns without acquiring it otherwise.
boolean	tryWriteLock() Acquires the write lock for the current thread only if possible without blocking the thread; returns without acquiring it otherwise.
void	writeLock() Acquires the write lock for the current thread, blocking until available.
void	writeLockFromReadLock() Acquires the write lock for the current thread, upgrading from a read lock if necessary, blocking until available.
void	writeUnlock() Releases the write lock for the current thread.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_WAIT_INTERVAL

public static final int DEFAULT_WAIT_INTERVAL

See Also:

Constant Field Values

DEFAULT_DEADLOCK_INTERVAL

public static final int DEFAULT_DEADLOCK_INTERVAL

See Also:

Constant Field Values

DEFAULT_HISTORY_LIMIT

public static final int DEFAULT_HISTORY_LIMIT

DEFAULT_OPTIONS

public static final java.util.EnumSet<ReadWriteLock.Options> DEFAULT_OPTIONS

Constructor Detail

ReadWriteLock

public ReadWriteLock()

Creates an anonymous lock.

ReadWriteLock

public ReadWriteLock(java.lang.String name)

Creates a named lock.

ReadWriteLock

public ReadWriteLock(java.lang.String name,
                     java.util.EnumSet<ReadWriteLock.Options> options,
                     int waitInterval,
                     int deadlockInterval,
                     int historyLimit)

Creates a named lock with specified options.

Method Detail

setName

public final void setName(java.lang.String name)

Sets the name of this lock. The name is only used for diagnostic purposes.

getName

public final java.lang.String getName()

Gets the name of this lock. The name is only used for diagnostic purposes.

readLock

public void readLock()

Acquires a read lock for the current thread, blocking until available.

tryReadLock

public boolean tryReadLock()

Acquires a read lock for the current thread only if possible without blocking the thread; returns without acquiring it otherwise.

Returns:

true if the lock was acquired, false otherwise.

readUnlock

public void readUnlock()

Releases a read lock for the current thread.

Throws:

java.lang.IllegalMonitorStateException - if the current thread does not hold a read lock.

addWriteLockRequestListener

public boolean addWriteLockRequestListener(WriteLockRequestListener listener)

Adds a WriteLockRequestListener on behalf of the current thread. The listener will be notified if a thread requests a write lock.

Returns:

whether other threads are already waiting for a write lock.

Throws:

java.lang.IllegalMonitorStateException - if the current thread does not hold a read or write lock.

removeWriteLockRequestListener

public void removeWriteLockRequestListener(WriteLockRequestListener listener)

Removes a WriteLockRequestListener.

Throws:

java.lang.IllegalMonitorStateException - if the current thread does not hold a read or write lock.

writeLock

public void writeLock()

Acquires the write lock for the current thread, blocking until available.

tryWriteLock

public boolean tryWriteLock()

Acquires the write lock for the current thread only if possible without blocking the thread; returns without acquiring it otherwise.

Returns:

true if the lock was acquired, false otherwise.

writeUnlock

public void writeUnlock()

Releases the write lock for the current thread.

Throws:

java.lang.IllegalMonitorStateException - if the current thread does not hold the write lock.

writeLockFromReadLock

public void writeLockFromReadLock()

Acquires the write lock for the current thread, upgrading from a read lock if necessary, blocking until available. This is a "safe upgrade", which means that all read locks held by the current thread will be released, the write lock will be acquired, and then the read locks will be reacquired.

Because there is a point at which the current thread holds no locks, another thread will have the opportunity to acquire a lock and run. Any required preconditions that were checked under the read lock before the upgrade must be rechecked after the upgrade.

isReadLockHeld

public boolean isReadLockHeld()

Gets whether the current thread is holding a read lock for this lock. Note that a thread which acquires only a write lock for this lock will return false, use isLockHeld() to get whether the current thread is holding either a read or a write lock for this lock.

isWriteLockHeld

public boolean isWriteLockHeld()

Gets whether the current thread is holding a write lock for this lock.

isLockHeld

public boolean isLockHeld()

Gets whether the current thread is holding either a read or write lock for this lock.

getReadHoldCount

public int getReadHoldCount()

Gets the number of times the current thread has taken the read lock for this lock.

getWriteHoldCount

public int getWriteHoldCount()

Gets the number of times the current thread has taken the write lock for this lock.

appendSnapshot

public void appendSnapshot(java.lang.StringBuilder buffer)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setEventLog

public void setEventLog(Log log)

Sets or clears a logger for lock events. If the logger is set, non-nested lock requests, grants, and denials are logged, except for read requests and grants on the event thread, which are never logged.

Parameters:

log - The logger to set, or null to clear.

registerApiMethod

public static void registerApiMethod(java.lang.String className,
                                     java.lang.String methodName)

Registers a method as a lock API method. When logging lock exceptions (currently only done for lock upgrades), lock API methods are excluded from blame.

Parameters:

className - The qualified name of the class containing the lock API method.

methodName - The name of the lock API method.

Skip navigation links