Guava: Google Core Libraries for Java 33.1.0-jre · com.google.common.util.concurrent.Monitor

A synchronization abstraction supporting waiting on arbitrary boolean conditions.

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();
    }
  }
}

Nested and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	Monitor.Guard A boolean condition for which a thread may wait.

Field Summary

Modifier and Type	Field and Description
private Monitor.Guard	activeGuards The guards associated with this monitor that currently have waiters (`waiterCount > 0`).
private final boolean	fair Whether this monitor is fair.
private final ReentrantLock	lock The lock underlying this monitor.

Constructor Summary

Access	Constructor and Description
public	Monitor() Creates a monitor with a non-fair (but fast) ordering policy.
public	Monitor(boolean whether this monitor should use a fair ordering policy rather than a non-fair (but fast) one fair) Creates a monitor with the given ordering policy.

Method Summary

Modifier and Type	Method and Description
private 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.
public void	enter() Enters this monitor.
public boolean	Returns: whether the monitor was entered enter(Duration time) Enters this monitor.
public boolean	Returns: whether the monitor was entered enter(long time, TimeUnit unit) Enters this monitor.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIf(Monitor.Guard guard) Enters this monitor if the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIf(Monitor.Guard guard, Duration time) Enters this monitor if the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIf(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor if the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIfInterruptibly(Monitor.Guard guard) Enters this monitor if the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIfInterruptibly(Monitor.Guard guard, Duration time) Enters this monitor if the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterIfInterruptibly(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor if the guard is satisfied.
public void	enterInterruptibly() Enters this monitor.
public boolean	Returns: whether the monitor was entered enterInterruptibly(Duration time) Enters this monitor.
public boolean	Returns: whether the monitor was entered enterInterruptibly(long time, TimeUnit unit) Enters this monitor.
public void	enterWhen(Monitor.Guard guard) Enters this monitor when the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterWhen(Monitor.Guard guard, Duration time) Enters this monitor when the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterWhen(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor when the guard is satisfied.
public void	enterWhenUninterruptibly(Monitor.Guard guard) Enters this monitor when the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterWhenUninterruptibly(Monitor.Guard guard, Duration time) Enters this monitor when the guard is satisfied.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied enterWhenUninterruptibly(Monitor.Guard guard, long time, TimeUnit unit) Enters this monitor when the guard is satisfied.
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.
public int	getQueueLength() Returns an estimate of the number of threads waiting to enter this monitor.
public int	getWaitQueueLength(Monitor.Guard guard) Returns an estimate of the number of threads waiting for the given guard to become satisfied.
public boolean	hasQueuedThread(Thread thread) Queries whether the given thread is waiting to enter this monitor.
public boolean	hasQueuedThreads() Returns whether any threads are waiting to enter this monitor.
public 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.
public boolean	isFair() Returns whether this monitor is using a fair ordering policy.
public boolean	isOccupied() Returns whether this monitor is occupied by any thread.
public boolean	isOccupiedByCurrentThread() 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.
public void	leave() Leaves this monitor.
public Monitor.Guard	newGuard(final BooleanSupplier the new guard's boolean condition (see `isSatisfied()`) 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	signalAllWaiters() Signals all threads waiting on guards.
private void	signalNextWaiter() 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.
public boolean	Returns: whether the monitor was entered tryEnter() Enters this monitor if it is possible to do so immediately.
public boolean	Returns: whether the monitor was entered, which guarantees that the guard is now satisfied tryEnterIf(Monitor.Guard guard) Enters this monitor if it is possible to do so immediately and the guard is satisfied.
public void	waitFor(Monitor.Guard guard) Waits for the guard to be satisfied.
public boolean	Returns: whether the guard is now satisfied waitFor(Monitor.Guard guard, Duration time) Waits for the guard to be satisfied.
public boolean	Returns: whether the guard is now satisfied waitFor(Monitor.Guard guard, long time, TimeUnit unit) Waits for the guard to be satisfied.
public void	waitForUninterruptibly(Monitor.Guard guard) Waits for the guard to be satisfied.
public boolean	Returns: whether the guard is now satisfied waitForUninterruptibly(Monitor.Guard guard, Duration time) Waits for the guard to be satisfied.
public boolean	Returns: whether the guard is now satisfied waitForUninterruptibly(Monitor.Guard guard, long time, TimeUnit unit) Waits for the guard to be satisfied.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

activeGuards	back to summary
private Monitor.Guard activeGuards The guards associated with this monitor that currently have waiters (`waiterCount > 0`). A linked list threaded through the Guard.next field. Annotations @GuardedBy:lock @CheckForNull

fair	back to summary
private final boolean fair Whether this monitor is fair.

lock	back to summary
private final ReentrantLock lock The lock underlying this monitor.

Constructor Detail

Monitor	back to summary
public Monitor() Creates a monitor with a non-fair (but fast) ordering policy. Equivalent to `Monitor(false)`.

Monitor	back to summary
public Monitor(boolean fair) Creates a monitor with the given ordering policy. Parameters fair:boolean whether this monitor should use a fair ordering policy rather than a non-fair (but fast) one

Monitor

Modifier and Type	Field and Description
pack-priv final Condition	condition
pack-priv final Monitor	monitor
pack-priv Monitor.Guard	next The next active guard
pack-priv int	waiterCount

public final Class Monitor

Comparison with synchronized and ReentrantLock

synchronized

ReentrantLock

Monitor

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public abstract Class Monitor.Guard

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

Comparison with `synchronized` and `ReentrantLock`

`synchronized`

`ReentrantLock`

`Monitor`