@Beta @GwtIncompatible public final class Monitor extends Object
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
}
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();
}
}
}
Modifier and Type | Class and Description |
---|---|
static class |
Monitor.Guard
A boolean condition for which a thread may wait.
|
Constructor and Description |
---|
Monitor()
Creates a monitor with a non-fair (but fast) ordering policy.
|
Monitor(boolean fair)
Creates a monitor with the given ordering policy.
|
Modifier and Type | Method and Description |
---|---|
void |
enter()
Enters this monitor.
|
boolean |
enter(long time,
TimeUnit unit)
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 |
enterIfInterruptibly(Monitor.Guard guard)
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.
|
void |
enterInterruptibly()
Enters this monitor.
|
boolean |
enterInterruptibly(long time,
TimeUnit unit)
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.
|
void |
enterWhenUninterruptibly(Monitor.Guard guard)
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.
|
int |
getOccupiedDepth()
Returns the number of times the current thread has entered this monitor in excess of the number
of times it has left.
|
int |
getQueueLength()
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 |
hasQueuedThreads()
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.
|
boolean |
isFair()
Returns whether this monitor is using a fair ordering policy.
|
boolean |
isOccupied()
Returns whether this monitor is occupied by any thread.
|
boolean |
isOccupiedByCurrentThread()
Returns whether the current thread is occupying this monitor (has entered more times than it
has left).
|
void |
leave()
Leaves this monitor.
|
Monitor.Guard |
newGuard(BooleanSupplier isSatisfied)
Creates a new guard for this monitor.
|
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.
|
void |
waitForUninterruptibly(Monitor.Guard guard)
Waits for the guard to be satisfied.
|
boolean |
waitForUninterruptibly(Monitor.Guard guard,
long time,
TimeUnit unit)
Waits for the guard to be satisfied.
|
public Monitor()
Monitor(false)
.public Monitor(boolean fair)
fair
- whether this monitor should use a fair ordering policy rather than a non-fair (but
fast) onepublic Monitor.Guard newGuard(BooleanSupplier isSatisfied)
isSatisfied
- the new guard's boolean condition (see isSatisfied()
)public void enter()
public boolean enter(long time, TimeUnit unit)
public void enterInterruptibly() throws InterruptedException
InterruptedException
- if interrupted while waitingpublic boolean enterInterruptibly(long time, TimeUnit unit) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic boolean tryEnter()
Note: This method disregards the fairness setting of this monitor.
public void enterWhen(Monitor.Guard guard) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic boolean enterWhen(Monitor.Guard guard, long time, TimeUnit unit) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic void enterWhenUninterruptibly(Monitor.Guard guard)
public boolean enterWhenUninterruptibly(Monitor.Guard guard, long time, TimeUnit unit)
public boolean enterIf(Monitor.Guard guard)
public boolean enterIf(Monitor.Guard guard, long time, TimeUnit unit)
public boolean enterIfInterruptibly(Monitor.Guard guard) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic boolean enterIfInterruptibly(Monitor.Guard guard, long time, TimeUnit unit) throws InterruptedException
InterruptedException
public boolean tryEnterIf(Monitor.Guard guard)
Note: This method disregards the fairness setting of this monitor.
public void waitFor(Monitor.Guard guard) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic boolean waitFor(Monitor.Guard guard, long time, TimeUnit unit) throws InterruptedException
InterruptedException
- if interrupted while waitingpublic void waitForUninterruptibly(Monitor.Guard guard)
public boolean waitForUninterruptibly(Monitor.Guard guard, long time, TimeUnit unit)
public void leave()
public boolean isFair()
public boolean isOccupied()
public boolean isOccupiedByCurrentThread()
public int getOccupiedDepth()
public int getQueueLength()
public boolean hasQueuedThreads()
true
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.public boolean hasQueuedThread(Thread thread)
true
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.public boolean hasWaiters(Monitor.Guard guard)
true
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.public int getWaitQueueLength(Monitor.Guard guard)
Copyright © 2010–2019. All rights reserved.