Package com.unboundid.util
Class CloseableLock
- java.lang.Object
-
- com.unboundid.util.CloseableLock
-
@Mutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class CloseableLock extends java.lang.Object
This class provides an implementation of a reentrant lock that can be used with the Java try-with-resources facility. It does not implement thejava.util.concurrent.locks.Lock
interface in order to ensure that it can only be used through lock-with-resources mechanism, but it uses ajava.util.concurrent.locks.ReentrantLock
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 (CloseableLock.Lock lock = closeableLock.tryLock(5L, TimeUnit.SECONDS)) { // NOTE: If you don't reference the lock object inside the try block, the // compiler will issue a warning. lock.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 Description class
CloseableLock.Lock
This class provides aCloseable
implementation that may be used to unlock aCloseableLock
via Java's try-with-resources facility.
-
Constructor Summary
Constructors Constructor Description CloseableLock()
Creates a new instance of this lock with a non-fair ordering policy.CloseableLock(boolean fair)
Creates a new instance of this lock with the specified ordering policy.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description int
getHoldCount()
Retrieves the number of holds that the current thread has on the lock.int
getQueueLength()
Retrieves an estimate of the number of threads currently waiting to acquire this lock.boolean
hasQueuedThread(java.lang.Thread thread)
Indicates whether the specified thread is currently waiting to acquire this lock, orfalse
if not.boolean
hasQueuedThreads()
Indicates whether any threads are currently waiting to acquire this lock.boolean
isFair()
Indicates whether this lock uses fair ordering.boolean
isHeldByCurrentThread()
Indicates whether this lock is currently held by the current thread.boolean
isLocked()
Indicates whether this lock is currently held by any thread.CloseableLock.Lock
lock()
Acquires this lock, blocking until the lock is available.CloseableLock.Lock
lockInterruptibly()
Acquires this lock, blocking until the lock is available.java.lang.String
toString()
Retrieves a string representation of this lock.CloseableLock.Lock
tryLock(long waitTime, java.util.concurrent.TimeUnit timeUnit)
Tries to acquire the lock, waiting up to the specified length of time for it to become available.
-
-
-
Constructor Detail
-
CloseableLock
public CloseableLock()
Creates a new instance of this lock with a non-fair ordering policy.
-
CloseableLock
public CloseableLock(boolean fair)
Creates a new instance of this lock with the specified ordering policy.- Parameters:
fair
- Indicates whether the lock should use fair ordering. Iftrue
, 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. Iffalse
, then no guarantee will be made about the order. Fair ordering can incur a performance penalty.
-
-
Method Detail
-
lock
@NotNull public CloseableLock.Lock lock()
Acquires this lock, blocking until the lock is available.- Returns:
- The
CloseableLock.Lock
instance that may be used to perform the unlock via the try-with-resources facility.
-
lockInterruptibly
@NotNull public CloseableLock.Lock lockInterruptibly() throws java.lang.InterruptedException
Acquires this lock, blocking until the lock is available.- Returns:
- The
CloseableLock.Lock
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.
-
tryLock
@NotNull public CloseableLock.Lock tryLock(long waitTime, @NotNull java.util.concurrent.TimeUnit timeUnit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException
Tries to acquire the 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 thewaitTime
value.- Returns:
- The
CloseableLock.Lock
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, orfalse
if not.
-
isLocked
public boolean isLocked()
Indicates whether this lock is currently held by any thread.- Returns:
true
if this lock is currently held by any thread, orfalse
if not.
-
isHeldByCurrentThread
public boolean isHeldByCurrentThread()
Indicates whether this lock is currently held by the current thread.- Returns:
true
if this lock is currently held by the current thread, orfalse
if not.
-
getHoldCount
public int getHoldCount()
Retrieves the number of holds that the current thread has on the lock.- Returns:
- The number of holds that the current thread has on the lock.
-
hasQueuedThreads
public boolean hasQueuedThreads()
Indicates whether any threads are currently waiting to acquire this lock.- Returns:
true
if any threads are currently waiting to acquire this lock, orfalse
if not.
-
hasQueuedThread
public boolean hasQueuedThread(@NotNull java.lang.Thread thread)
Indicates whether the specified thread is currently waiting to acquire this lock, orfalse
if not.- Parameters:
thread
- The thread for which to make the determination. It must not benull
.- Returns:
true
if the specified thread is currently waiting to acquire this lock, orfalse
if not.
-
getQueueLength
public int getQueueLength()
Retrieves an estimate of the number of threads currently waiting to acquire this lock.- Returns:
- An estimate of the number of threads currently waiting to acquire this lock.
-
-