com.unboundid.util

Class CloseableReadWriteLock

java.lang.Object

com.unboundid.util.CloseableReadWriteLock

@Mutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class CloseableReadWriteLock
extends java.lang.Object

This class provides an implementation of a reentrant read-write lock that can be used with the Java try-with-resources facility. With a read-write lock, either exactly one thread can hold the write lock while no other threads hold read locks, or zero or more threads can hold read locks while no thread holds the write lock. The one exception to this policy is that the thread that holds the write lock can downgrade will be permitted to acquire a read lock before it releases the write lock to downgrade from a write lock to a read lock while ensuring that no other thread is permitted to acquire the write lock while it is in the process of downgrading.

This class does not implement the java.util.concurrent.locks.ReadWriteLock interface in order to ensure that it can only be used through the try-with-resources mechanism, but it uses a java.util.concurrent.locks.ReentrantReadWriteLock behind the scenes to provide its functionality.

Example

The following example demonstrates how to use this lock using the Java try-with-resources facility:

 // Wait for up to 5 seconds to acquire the lock.
 try (CloseableReadWriteLock.WriteLock writeLock =
           closeableReadWriteLock.tryLock(5L, TimeUnit.SECONDS))
 {
   // NOTE:  If you don't reference the lock object inside the try block, the
   // compiler will issue a warning.
   writeLock.avoidCompilerWarning();

   // Do something while the lock is held.  The lock will automatically be
   // released once code execution leaves this block.
 }
 catch (final InterruptedException e)
 {
   // The thread was interrupted before the lock could be acquired.
 }
 catch (final TimeoutException)
 {
   // The lock could not be acquired within the specified 5-second timeout.
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CloseableReadWriteLock.ReadLock This class provides a Closeable implementation that may be used to unlock a CloseableReadWriteLock's read lock via Java's try-with-resources facility.
class	CloseableReadWriteLock.WriteLock This class provides a Closeable implementation that may be used to unlock a CloseableReadWriteLock's write lock via Java's try-with-resources facility.

Constructor Summary

Constructors

Constructor and Description
CloseableReadWriteLock() Creates a new instance of this read-write lock with a non-fair ordering policy.
CloseableReadWriteLock(boolean fair) Creates a new instance of this read-write lock with the specified ordering policy.

Method Summary

Modifier and Type	Method and Description
int	getQueueLength() Retrieves an estimate of the number of threads currently waiting to acquire either the write or read lock.
int	getReadHoldCount() Retrieves the number of holds that the current thread has on the read lock.
int	getReadLockCount() Retrieves the number of threads that currently hold the read lock.
int	getWriteHoldCount() Retrieves the number of holds that the current thread has on the write lock.
boolean	hasQueuedThread(java.lang.Thread thread) Indicates whether the specified thread is currently waiting to acquire either the write or read lock.
boolean	hasQueuedThreads() Indicates whether any threads are currently waiting to acquire either the write or read lock.
boolean	isFair() Indicates whether this lock uses fair ordering.
boolean	isWriteLocked() Indicates whether the write lock is currently held by any thread.
boolean	isWriteLockedByCurrentThread() Indicates whether the write lock is currently held by the current thread.
CloseableReadWriteLock.ReadLock	lockRead() Acquires a read lock, blocking until the lock is available.
CloseableReadWriteLock.ReadLock	lockReadInterruptibly() Acquires a read lock, blocking until the lock is available.
CloseableReadWriteLock.WriteLock	lockWrite() Acquires the write lock, blocking until the lock is available.
CloseableReadWriteLock.WriteLock	lockWriteInterruptibly() Acquires the write lock, blocking until the lock is available.
java.lang.String	toString() Retrieves a string representation of this read-write lock.
CloseableReadWriteLock.ReadLock	tryLockRead(long waitTime, java.util.concurrent.TimeUnit timeUnit) Tries to acquire a read lock, waiting up to the specified length of time for it to become available.
CloseableReadWriteLock.WriteLock	tryLockWrite(long waitTime, java.util.concurrent.TimeUnit timeUnit) Tries to acquire the write lock, waiting up to the specified length of time for it to become available.

Methods inherited from class java.lang.Object

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

Constructor Detail

CloseableReadWriteLock

public CloseableReadWriteLock()

Creates a new instance of this read-write lock with a non-fair ordering policy.

CloseableReadWriteLock

public CloseableReadWriteLock(boolean fair)

Creates a new instance of this read-write lock with the specified ordering policy.

Parameters:

fair - Indicates whether the lock should use fair ordering. If true, then if multiple threads are waiting on the lock, then the one that has been waiting the longest is the one that will get it. If false, then no guarantee will be made about the order. Fair ordering can incur a performance penalty.

Method Detail

lockWrite

@NotNull
public CloseableReadWriteLock.WriteLock lockWrite()

Acquires the write lock, blocking until the lock is available.

Returns:

The CloseableReadWriteLock.WriteLock instance that may be used to perform the unlock via the try-with-resources facility.

lockWriteInterruptibly

@NotNull
public CloseableReadWriteLock.WriteLock lockWriteInterruptibly()
                                                                 throws java.lang.InterruptedException

Acquires the write lock, blocking until the lock is available.

Returns:

The CloseableReadWriteLock.WriteLock instance that may be used to perform the unlock via the try-with-resources facility.

Throws:

java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.

tryLockWrite

@NotNull
public CloseableReadWriteLock.WriteLock tryLockWrite(long waitTime,
                                                              @NotNull
                                                              java.util.concurrent.TimeUnit timeUnit)
                                                       throws java.lang.InterruptedException,
                                                              java.util.concurrent.TimeoutException

Tries to acquire the write lock, waiting up to the specified length of time for it to become available.

Parameters:

waitTime - The maximum length of time to wait for the lock. It must be greater than zero.

timeUnit - The time unit that should be used when evaluating the waitTime value.

Returns:

The CloseableReadWriteLock.WriteLock instance that may be used to perform the unlock via the try-with-resources facility.

Throws:

java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.

java.util.concurrent.TimeoutException - If the lock could not be acquired within the specified length of time.

lockRead

@NotNull
public CloseableReadWriteLock.ReadLock lockRead()

Acquires a read lock, blocking until the lock is available.

Returns:

The CloseableReadWriteLock.ReadLock instance that may be used to perform the unlock via the try-with-resources facility.

lockReadInterruptibly

@NotNull
public CloseableReadWriteLock.ReadLock lockReadInterruptibly()
                                                               throws java.lang.InterruptedException

Acquires a read lock, blocking until the lock is available.

Returns:

The CloseableReadWriteLock.ReadLock instance that may be used to perform the unlock via the try-with-resources facility.

Throws:

java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.

tryLockRead

@NotNull
public CloseableReadWriteLock.ReadLock tryLockRead(long waitTime,
                                                            @NotNull
                                                            java.util.concurrent.TimeUnit timeUnit)
                                                     throws java.lang.InterruptedException,
                                                            java.util.concurrent.TimeoutException

Tries to acquire a read lock, waiting up to the specified length of time for it to become available.

Parameters:

waitTime - The maximum length of time to wait for the lock. It must be greater than zero.

timeUnit - The time unit that should be used when evaluating the waitTime value.

Returns:

The CloseableReadWriteLock.ReadLock instance that may be used to perform the unlock via the try-with-resources facility.

Throws:

java.lang.InterruptedException - If the thread is interrupted while waiting to acquire the lock.

java.util.concurrent.TimeoutException - If the lock could not be acquired within the specified length of time.

isFair

public boolean isFair()

Indicates whether this lock uses fair ordering.

Returns:

true if this lock uses fair ordering, or false if not.

isWriteLocked

public boolean isWriteLocked()

Indicates whether the write lock is currently held by any thread.

Returns:

true if the write lock is currently held by any thread, or false if not.

isWriteLockedByCurrentThread

public boolean isWriteLockedByCurrentThread()

Indicates whether the write lock is currently held by the current thread.

Returns:

true if the write lock is currently held by the current thread, or false if not.

getWriteHoldCount

public int getWriteHoldCount()

Retrieves the number of holds that the current thread has on the write lock.

Returns:

The number of holds that the current thread has on the write lock.

getReadLockCount

public int getReadLockCount()

Retrieves the number of threads that currently hold the read lock.

Returns:

The number of threads that currently hold the read lock.

getReadHoldCount

public int getReadHoldCount()

Retrieves the number of holds that the current thread has on the read lock.

Returns:

The number of holds that the current thread has on the read lock.

hasQueuedThreads

public boolean hasQueuedThreads()

Indicates whether any threads are currently waiting to acquire either the write or read lock.

Returns:

true if any threads are currently waiting to acquire either the write or read lock, or false if not.

hasQueuedThread

public boolean hasQueuedThread(@NotNull
                               java.lang.Thread thread)

Indicates whether the specified thread is currently waiting to acquire either the write or read lock.

Parameters:

thread - The thread for which to make the determination. It must not be null.

Returns:

true if the specified thread is currently waiting to acquire either the write or read lock, or false if not.

getQueueLength

public int getQueueLength()

Retrieves an estimate of the number of threads currently waiting to acquire either the write or read lock.

Returns:

An estimate of the number of threads currently waiting to acquire either the write or read lock.

toString

@NotNull
public java.lang.String toString()

Retrieves a string representation of this read-write lock.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this read-write lock.