Class Monitor
This class is intended as a replacement for ReentrantLock
. Code using Monitor
is less error-prone and more readable than code using ReentrantLock
, without significant
performance loss. Monitor
even has the potential for performance gain by optimizing the
evaluation and signaling of conditions. Signaling is entirely implicit. By
eliminating explicit signaling, this class can guarantee that only one thread is awakened when a
condition becomes true (no "signaling storms" due to use of Condition.signalAll
) and that no signals are lost
(no "hangs" due to incorrect use of Condition.signal
).
A thread is said to occupy a monitor if it has entered the monitor but not yet left. Only one thread may occupy a given monitor at any moment. A monitor is also reentrant, so a thread may enter a monitor any number of times, and then must leave the same number of times. The enter and leave operations have the same synchronization semantics as the built-in Java language synchronization primitives.
A call to any of the enter methods with void return type should always be followed immediately by a try/finally block to ensure that the current thread leaves the monitor cleanly:
monitor.enter();
try {
// do things while occupying the monitor
} finally {
monitor.leave();
}
A call to any of the enter methods with boolean return type should always appear as the condition of an if statement containing a try/finally block to ensure that the current thread leaves the monitor cleanly:
if (monitor.tryEnter()) {
try {
// do things while occupying the monitor
} finally {
monitor.leave();
}
} else {
// do other things since the monitor was not available
}
Comparison with synchronized
and ReentrantLock
The following examples show a simple threadsafe holder expressed using synchronized
,
ReentrantLock
, and Monitor
.
synchronized
This version is the fewest lines of code, largely because the synchronization mechanism used
is built into the language and runtime. But the programmer has to remember to avoid a couple of
common bugs: The wait()
must be inside a while
instead of an if
, and
notifyAll()
must be used instead of notify()
because there are two different
logical conditions being awaited.
public class SafeBox<V> {
private V value;
public synchronized V get() throws InterruptedException {
while (value == null) {
wait();
}
V result = value;
value = null;
notifyAll();
return result;
}
public synchronized void set(V newValue) throws InterruptedException {
while (value != null) {
wait();
}
value = newValue;
notifyAll();
}
}
ReentrantLock
This version is much more verbose than the synchronized
version, and still suffers
from the need for the programmer to remember to use while
instead of if
. However,
one advantage is that we can introduce two separate Condition
objects, which allows us to
use signal()
instead of signalAll()
, which may be a performance benefit.
public class SafeBox<V> {
private V value;
private final ReentrantLock lock = new ReentrantLock();
private final Condition valuePresent = lock.newCondition();
private final Condition valueAbsent = lock.newCondition();
public V get() throws InterruptedException {
lock.lock();
try {
while (value == null) {
valuePresent.await();
}
V result = value;
value = null;
valueAbsent.signal();
return result;
} finally {
lock.unlock();
}
}
public void set(V newValue) throws InterruptedException {
lock.lock();
try {
while (value != null) {
valueAbsent.await();
}
value = newValue;
valuePresent.signal();
} finally {
lock.unlock();
}
}
}
Monitor
This version adds some verbosity around the Guard
objects, but removes that same
verbosity, and more, from the get
and set
methods. Monitor
implements the
same efficient signaling as we had to hand-code in the ReentrantLock
version above.
Finally, the programmer no longer has to hand-code the wait loop, and therefore doesn't have to
remember to use while
instead of if
.
public class SafeBox<V> {
private V value;
private final Monitor monitor = new Monitor();
private final Monitor.Guard valuePresent = monitor.newGuard(() -> value != null);
private final Monitor.Guard valueAbsent = monitor.newGuard(() -> value == null);
public V get() throws InterruptedException {
monitor.enterWhen(valuePresent);
try {
V result = value;
value = null;
return result;
} finally {
monitor.leave();
}
}
public void set(V newValue) throws InterruptedException {
monitor.enterWhen(valueAbsent);
try {
value = newValue;
} finally {
monitor.leave();
}
}
}
- Since:
- 10.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
A boolean condition for which a thread may wait. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Monitor.Guard
The guards associated with this monitor that currently have waiters (waiterCount > 0
).private final boolean
Whether this monitor is fair.private final ReentrantLock
The lock underlying this monitor. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate void
await
(Monitor.Guard guard, boolean signalBeforeWaiting) private boolean
awaitNanos
(Monitor.Guard guard, long nanos, boolean signalBeforeWaiting) Caller should check before calling that guard is not satisfied.private void
awaitUninterruptibly
(Monitor.Guard guard, boolean signalBeforeWaiting) private void
beginWaitingFor
(Monitor.Guard guard) Records that the current thread is about to wait on the specified guard.private void
endWaitingFor
(Monitor.Guard guard) Records that the current thread is no longer waiting on the specified guard.void
enter()
Enters this monitor.boolean
Enters this monitor.boolean
Enters this monitor.boolean
enterIf
(Monitor.Guard guard) Enters this monitor if the guard is satisfied.boolean
enterIf
(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor if the guard is satisfied.boolean
enterIf
(Monitor.Guard guard, Duration time) Enters this monitor if the guard is satisfied.boolean
Enters this monitor if the guard is satisfied.boolean
enterIfInterruptibly
(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor if the guard is satisfied.boolean
enterIfInterruptibly
(Monitor.Guard guard, Duration time) Enters this monitor if the guard is satisfied.void
Enters this monitor.boolean
enterInterruptibly
(long time, TimeUnit unit) Enters this monitor.boolean
enterInterruptibly
(Duration time) Enters this monitor.void
enterWhen
(Monitor.Guard guard) Enters this monitor when the guard is satisfied.boolean
enterWhen
(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor when the guard is satisfied.boolean
enterWhen
(Monitor.Guard guard, Duration time) Enters this monitor when the guard is satisfied.void
Enters this monitor when the guard is satisfied.boolean
enterWhenUninterruptibly
(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor when the guard is satisfied.boolean
enterWhenUninterruptibly
(Monitor.Guard guard, Duration time) Enters this monitor when the guard is satisfied.int
Returns the number of times the current thread has entered this monitor in excess of the number of times it has left.int
Returns an estimate of the number of threads waiting to enter this monitor.int
getWaitQueueLength
(Monitor.Guard guard) Returns an estimate of the number of threads waiting for the given guard to become satisfied.boolean
hasQueuedThread
(Thread thread) Queries whether the given thread is waiting to enter this monitor.boolean
Returns whether any threads are waiting to enter this monitor.boolean
hasWaiters
(Monitor.Guard guard) Queries whether any threads are waiting for the given guard to become satisfied.private static long
initNanoTime
(long timeoutNanos) Returns System.nanoTime() unless the timeout has already elapsed.boolean
isFair()
Returns whether this monitor is using a fair ordering policy.boolean
Returns whether this monitor is occupied by any thread.boolean
Returns whether the current thread is occupying this monitor (has entered more times than it has left).private boolean
isSatisfied
(Monitor.Guard guard) Exactly like guard.isSatisfied(), but in addition signals all waiting threads in the (hopefully unlikely) event that isSatisfied() throws.void
leave()
Leaves this monitor.newGuard
(BooleanSupplier isSatisfied) Creates a new guard for this monitor.private static long
remainingNanos
(long startTime, long timeoutNanos) Returns the remaining nanos until the given timeout, or 0L if the timeout has already elapsed.private void
Signals all threads waiting on guards.private void
Signals some other thread waiting on a satisfied guard, if one exists.private static long
toSafeNanos
(long time, TimeUnit unit) Returns unit.toNanos(time), additionally ensuring the returned value is not at risk of overflowing or underflowing, by bounding the value between 0 and (Long.MAX_VALUE / 4) * 3.boolean
tryEnter()
Enters this monitor if it is possible to do so immediately.boolean
tryEnterIf
(Monitor.Guard guard) Enters this monitor if it is possible to do so immediately and the guard is satisfied.void
waitFor
(Monitor.Guard guard) Waits for the guard to be satisfied.boolean
waitFor
(Monitor.Guard guard, long time, TimeUnit unit) Waits for the guard to be satisfied.boolean
waitFor
(Monitor.Guard guard, Duration time) Waits for the guard to be satisfied.void
Waits for the guard to be satisfied.boolean
waitForUninterruptibly
(Monitor.Guard guard, long time, TimeUnit unit) Waits for the guard to be satisfied.boolean
waitForUninterruptibly
(Monitor.Guard guard, Duration time) Waits for the guard to be satisfied.
-
Field Details
-
fair
private final boolean fairWhether this monitor is fair. -
lock
The lock underlying this monitor. -
activeGuards
The guards associated with this monitor that currently have waiters (waiterCount > 0
). A linked list threaded through the Guard.next field.
-
-
Constructor Details
-
Monitor
public Monitor()Creates a monitor with a non-fair (but fast) ordering policy. Equivalent toMonitor(false)
. -
Monitor
public Monitor(boolean fair) Creates a monitor with the given ordering policy.- Parameters:
fair
- whether this monitor should use a fair ordering policy rather than a non-fair (but fast) one
-
-
Method Details
-
newGuard
Creates a new guard for this monitor.- Parameters:
isSatisfied
- the new guard's boolean condition (seeisSatisfied()
)- Since:
- 21.0
-
enter
public void enter()Enters this monitor. Blocks indefinitely. -
enter
Enters this monitor. Blocks at most the given time.- Returns:
- whether the monitor was entered
- Since:
- 28.0
-
enter
Enters this monitor. Blocks at most the given time.- Returns:
- whether the monitor was entered
-
enterInterruptibly
Enters this monitor. Blocks indefinitely, but may be interrupted.- Throws:
InterruptedException
- if interrupted while waiting
-
enterInterruptibly
Enters this monitor. Blocks at most the given time, and may be interrupted.- Returns:
- whether the monitor was entered
- Throws:
InterruptedException
- if interrupted while waiting- Since:
- 28.0
-
enterInterruptibly
Enters this monitor. Blocks at most the given time, and may be interrupted.- Returns:
- whether the monitor was entered
- Throws:
InterruptedException
- if interrupted while waiting
-
tryEnter
public boolean tryEnter()Enters this monitor if it is possible to do so immediately. Does not block.Note: This method disregards the fairness setting of this monitor.
- Returns:
- whether the monitor was entered
-
enterWhen
Enters this monitor when the guard is satisfied. Blocks indefinitely, but may be interrupted.- Throws:
InterruptedException
- if interrupted while waiting
-
enterWhen
Enters this monitor when the guard is satisfied. Blocks at most the given time, including both the time to acquire the lock and the time to wait for the guard to be satisfied, and may be interrupted.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Throws:
InterruptedException
- if interrupted while waiting- Since:
- 28.0
-
enterWhen
Enters this monitor when the guard is satisfied. Blocks at most the given time, including both the time to acquire the lock and the time to wait for the guard to be satisfied, and may be interrupted.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Throws:
InterruptedException
- if interrupted while waiting
-
enterWhenUninterruptibly
Enters this monitor when the guard is satisfied. Blocks indefinitely. -
enterWhenUninterruptibly
Enters this monitor when the guard is satisfied. Blocks at most the given time, including both the time to acquire the lock and the time to wait for the guard to be satisfied.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Since:
- 28.0
-
enterWhenUninterruptibly
Enters this monitor when the guard is satisfied. Blocks at most the given time, including both the time to acquire the lock and the time to wait for the guard to be satisfied.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
-
enterIf
Enters this monitor if the guard is satisfied. Blocks indefinitely acquiring the lock, but does not wait for the guard to be satisfied.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
-
enterIf
Enters this monitor if the guard is satisfied. Blocks at most the given time acquiring the lock, but does not wait for the guard to be satisfied.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Since:
- 28.0
-
enterIf
Enters this monitor if the guard is satisfied. Blocks at most the given time acquiring the lock, but does not wait for the guard to be satisfied.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
-
enterIfInterruptibly
Enters this monitor if the guard is satisfied. Blocks indefinitely acquiring the lock, but does not wait for the guard to be satisfied, and may be interrupted.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Throws:
InterruptedException
- if interrupted while waiting
-
enterIfInterruptibly
Enters this monitor if the guard is satisfied. Blocks at most the given time acquiring the lock, but does not wait for the guard to be satisfied, and may be interrupted.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Throws:
InterruptedException
- Since:
- 28.0
-
enterIfInterruptibly
public boolean enterIfInterruptibly(Monitor.Guard guard, long time, TimeUnit unit) throws InterruptedException Enters this monitor if the guard is satisfied. Blocks at most the given time acquiring the lock, but does not wait for the guard to be satisfied, and may be interrupted.- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
- Throws:
InterruptedException
-
tryEnterIf
Enters this monitor if it is possible to do so immediately and the guard is satisfied. Does not block acquiring the lock and does not wait for the guard to be satisfied.Note: This method disregards the fairness setting of this monitor.
- Returns:
- whether the monitor was entered, which guarantees that the guard is now satisfied
-
waitFor
Waits for the guard to be satisfied. Waits indefinitely, but may be interrupted. May be called only by a thread currently occupying this monitor.- Throws:
InterruptedException
- if interrupted while waiting
-
waitFor
Waits for the guard to be satisfied. Waits at most the given time, and may be interrupted. May be called only by a thread currently occupying this monitor.- Returns:
- whether the guard is now satisfied
- Throws:
InterruptedException
- if interrupted while waiting- Since:
- 28.0
-
waitFor
Waits for the guard to be satisfied. Waits at most the given time, and may be interrupted. May be called only by a thread currently occupying this monitor.- Returns:
- whether the guard is now satisfied
- Throws:
InterruptedException
- if interrupted while waiting
-
waitForUninterruptibly
Waits for the guard to be satisfied. Waits indefinitely. May be called only by a thread currently occupying this monitor. -
waitForUninterruptibly
Waits for the guard to be satisfied. Waits at most the given time. May be called only by a thread currently occupying this monitor.- Returns:
- whether the guard is now satisfied
- Since:
- 28.0
-
waitForUninterruptibly
Waits for the guard to be satisfied. Waits at most the given time. May be called only by a thread currently occupying this monitor.- Returns:
- whether the guard is now satisfied
-
leave
public void leave()Leaves this monitor. May be called only by a thread currently occupying this monitor. -
isFair
public boolean isFair()Returns whether this monitor is using a fair ordering policy. -
isOccupied
public boolean isOccupied()Returns whether this monitor is occupied by any thread. This method is designed for use in monitoring of the system state, not for synchronization control. -
isOccupiedByCurrentThread
public boolean isOccupiedByCurrentThread()Returns whether the current thread is occupying this monitor (has entered more times than it has left). -
getOccupiedDepth
public int getOccupiedDepth()Returns the number of times the current thread has entered this monitor in excess of the number of times it has left. Returns 0 if the current thread is not occupying this monitor. -
getQueueLength
public int getQueueLength()Returns an estimate of the number of threads waiting to enter this monitor. The value is only an estimate because the number of threads may change dynamically while this method traverses internal data structures. This method is designed for use in monitoring of the system state, not for synchronization control. -
hasQueuedThreads
public boolean hasQueuedThreads()Returns whether any threads are waiting to enter this monitor. Note that because cancellations may occur at any time, atrue
return does not guarantee that any other thread will ever enter this monitor. This method is designed primarily for use in monitoring of the system state. -
hasQueuedThread
Queries whether the given thread is waiting to enter this monitor. Note that because cancellations may occur at any time, atrue
return does not guarantee that this thread will ever enter this monitor. This method is designed primarily for use in monitoring of the system state. -
hasWaiters
Queries whether any threads are waiting for the given guard to become satisfied. Note that because timeouts and interrupts may occur at any time, atrue
return does not guarantee that the guard becoming satisfied in the future will awaken any threads. This method is designed primarily for use in monitoring of the system state. -
getWaitQueueLength
Returns an estimate of the number of threads waiting for the given guard to become satisfied. Note that because timeouts and interrupts may occur at any time, the estimate serves only as an upper bound on the actual number of waiters. This method is designed for use in monitoring of the system state, not for synchronization control. -
toSafeNanos
Returns unit.toNanos(time), additionally ensuring the returned value is not at risk of overflowing or underflowing, by bounding the value between 0 and (Long.MAX_VALUE / 4) * 3. Actually waiting for more than 219 years is not supported! -
initNanoTime
private static long initNanoTime(long timeoutNanos) Returns System.nanoTime() unless the timeout has already elapsed. Returns 0L if and only if the timeout has already elapsed. -
remainingNanos
private static long remainingNanos(long startTime, long timeoutNanos) Returns the remaining nanos until the given timeout, or 0L if the timeout has already elapsed. Caller must have previously sanitized timeoutNanos using toSafeNanos. -
signalNextWaiter
private void signalNextWaiter()Signals some other thread waiting on a satisfied guard, if one exists.We manage calls to this method carefully, to signal only when necessary, but never losing a signal, which is the classic problem of this kind of concurrency construct. We must signal if the current thread is about to relinquish the lock and may have changed the state protected by the monitor, thereby causing some guard to be satisfied.
In addition, any thread that has been signalled when its guard was satisfied acquires the responsibility of signalling the next thread when it again relinquishes the lock. Unlike a normal Condition, there is no guarantee that an interrupted thread has not been signalled, since the concurrency control must manage multiple Conditions. So this method must generally be called when waits are interrupted.
On the other hand, if a signalled thread wakes up to discover that its guard is still not satisfied, it does *not* need to call this method before returning to wait. This can only happen due to spurious wakeup (ignorable) or another thread acquiring the lock before the current thread can and returning the guard to the unsatisfied state. In the latter case the other thread (last thread modifying the state protected by the monitor) takes over the responsibility of signalling the next waiter.
This method must not be called from within a beginWaitingFor/endWaitingFor block, or else the current thread's guard might be mistakenly signalled, leading to a lost signal.
-
isSatisfied
Exactly like guard.isSatisfied(), but in addition signals all waiting threads in the (hopefully unlikely) event that isSatisfied() throws. -
signalAllWaiters
private void signalAllWaiters()Signals all threads waiting on guards. -
beginWaitingFor
Records that the current thread is about to wait on the specified guard. -
endWaitingFor
Records that the current thread is no longer waiting on the specified guard. -
await
- Throws:
InterruptedException
-
awaitUninterruptibly
-
awaitNanos
private boolean awaitNanos(Monitor.Guard guard, long nanos, boolean signalBeforeWaiting) throws InterruptedException Caller should check before calling that guard is not satisfied.- Throws:
InterruptedException
-