Conditions (also known as condition queues or jaroslav@1890: * condition variables) provide a means for one thread to jaroslav@1890: * suspend execution (to "wait") until notified by another jaroslav@1890: * thread that some state condition may now be true. Because access jaroslav@1890: * to this shared state information occurs in different threads, it jaroslav@1890: * must be protected, so a lock of some form is associated with the jaroslav@1890: * condition. The key property that waiting for a condition provides jaroslav@1890: * is that it atomically releases the associated lock and jaroslav@1890: * suspends the current thread, just like {@code Object.wait}. jaroslav@1890: * jaroslav@1890: *
A {@code Condition} instance is intrinsically bound to a lock. jaroslav@1890: * To obtain a {@code Condition} instance for a particular {@link Lock} jaroslav@1890: * instance use its {@link Lock#newCondition newCondition()} method. jaroslav@1890: * jaroslav@1890: *
As an example, suppose we have a bounded buffer which supports jaroslav@1890: * {@code put} and {@code take} methods. If a jaroslav@1890: * {@code take} is attempted on an empty buffer, then the thread will block jaroslav@1890: * until an item becomes available; if a {@code put} is attempted on a jaroslav@1890: * full buffer, then the thread will block until a space becomes available. jaroslav@1890: * We would like to keep waiting {@code put} threads and {@code take} jaroslav@1890: * threads in separate wait-sets so that we can use the optimization of jaroslav@1890: * only notifying a single thread at a time when items or spaces become jaroslav@1890: * available in the buffer. This can be achieved using two jaroslav@1890: * {@link Condition} instances. jaroslav@1890: *
jaroslav@1890: * class BoundedBuffer {
jaroslav@1890: * final Lock lock = new ReentrantLock();
jaroslav@1890: * final Condition notFull = lock.newCondition();
jaroslav@1890: * final Condition notEmpty = lock.newCondition();
jaroslav@1890: *
jaroslav@1890: * final Object[] items = new Object[100];
jaroslav@1890: * int putptr, takeptr, count;
jaroslav@1890: *
jaroslav@1890: * public void put(Object x) throws InterruptedException {
jaroslav@1890: * lock.lock();
jaroslav@1890: * try {
jaroslav@1890: * while (count == items.length)
jaroslav@1890: * notFull.await();
jaroslav@1890: * items[putptr] = x;
jaroslav@1890: * if (++putptr == items.length) putptr = 0;
jaroslav@1890: * ++count;
jaroslav@1890: * notEmpty.signal();
jaroslav@1890: * } finally {
jaroslav@1890: * lock.unlock();
jaroslav@1890: * }
jaroslav@1890: * }
jaroslav@1890: *
jaroslav@1890: * public Object take() throws InterruptedException {
jaroslav@1890: * lock.lock();
jaroslav@1890: * try {
jaroslav@1890: * while (count == 0)
jaroslav@1890: * notEmpty.await();
jaroslav@1890: * Object x = items[takeptr];
jaroslav@1890: * if (++takeptr == items.length) takeptr = 0;
jaroslav@1890: * --count;
jaroslav@1890: * notFull.signal();
jaroslav@1890: * return x;
jaroslav@1890: * } finally {
jaroslav@1890: * lock.unlock();
jaroslav@1890: * }
jaroslav@1890: * }
jaroslav@1890: * }
jaroslav@1890: *
jaroslav@1890: *
jaroslav@1890: * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
jaroslav@1890: * this functionality, so there is no reason to implement this
jaroslav@1890: * sample usage class.)
jaroslav@1890: *
jaroslav@1890: * A {@code Condition} implementation can provide behavior and semantics jaroslav@1890: * that is jaroslav@1890: * different from that of the {@code Object} monitor methods, such as jaroslav@1890: * guaranteed ordering for notifications, or not requiring a lock to be held jaroslav@1890: * when performing notifications. jaroslav@1890: * If an implementation provides such specialized semantics then the jaroslav@1890: * implementation must document those semantics. jaroslav@1890: * jaroslav@1890: *
Note that {@code Condition} instances are just normal objects and can jaroslav@1890: * themselves be used as the target in a {@code synchronized} statement, jaroslav@1890: * and can have their own monitor {@link Object#wait wait} and jaroslav@1890: * {@link Object#notify notification} methods invoked. jaroslav@1890: * Acquiring the monitor lock of a {@code Condition} instance, or using its jaroslav@1890: * monitor methods, has no specified relationship with acquiring the jaroslav@1890: * {@link Lock} associated with that {@code Condition} or the use of its jaroslav@1890: * {@linkplain #await waiting} and {@linkplain #signal signalling} methods. jaroslav@1890: * It is recommended that to avoid confusion you never use {@code Condition} jaroslav@1890: * instances in this way, except perhaps within their own implementation. jaroslav@1890: * jaroslav@1890: *
Except where noted, passing a {@code null} value for any parameter jaroslav@1890: * will result in a {@link NullPointerException} being thrown. jaroslav@1890: * jaroslav@1890: *
When waiting upon a {@code Condition}, a "spurious jaroslav@1890: * wakeup" is permitted to occur, in jaroslav@1890: * general, as a concession to the underlying platform semantics. jaroslav@1890: * This has little practical impact on most application programs as a jaroslav@1890: * {@code Condition} should always be waited upon in a loop, testing jaroslav@1890: * the state predicate that is being waited for. An implementation is jaroslav@1890: * free to remove the possibility of spurious wakeups but it is jaroslav@1890: * recommended that applications programmers always assume that they can jaroslav@1890: * occur and so always wait in a loop. jaroslav@1890: * jaroslav@1890: *
The three forms of condition waiting jaroslav@1890: * (interruptible, non-interruptible, and timed) may differ in their ease of jaroslav@1890: * implementation on some platforms and in their performance characteristics. jaroslav@1890: * In particular, it may be difficult to provide these features and maintain jaroslav@1890: * specific semantics such as ordering guarantees. jaroslav@1890: * Further, the ability to interrupt the actual suspension of the thread may jaroslav@1890: * not always be feasible to implement on all platforms. jaroslav@1890: * jaroslav@1890: *
Consequently, an implementation is not required to define exactly the jaroslav@1890: * same guarantees or semantics for all three forms of waiting, nor is it jaroslav@1890: * required to support interruption of the actual suspension of the thread. jaroslav@1890: * jaroslav@1890: *
An implementation is required to jaroslav@1890: * clearly document the semantics and guarantees provided by each of the jaroslav@1890: * waiting methods, and when an implementation does support interruption of jaroslav@1890: * thread suspension then it must obey the interruption semantics as defined jaroslav@1890: * in this interface. jaroslav@1890: * jaroslav@1890: *
As interruption generally implies cancellation, and checks for jaroslav@1890: * interruption are often infrequent, an implementation can favor responding jaroslav@1890: * to an interrupt over normal method return. This is true even if it can be jaroslav@1890: * shown that the interrupt occurred after another action that may have jaroslav@1890: * unblocked the thread. An implementation should document this behavior. jaroslav@1890: * jaroslav@1890: * @since 1.5 jaroslav@1890: * @author Doug Lea jaroslav@1890: */ jaroslav@1890: public interface Condition { jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Causes the current thread to wait until it is signalled or jaroslav@1890: * {@linkplain Thread#interrupt interrupted}. jaroslav@1890: * jaroslav@1890: *
The lock associated with this {@code Condition} is atomically jaroslav@1890: * released and the current thread becomes disabled for thread scheduling jaroslav@1890: * purposes and lies dormant until one of four things happens: jaroslav@1890: *
In all cases, before this method can return the current thread must jaroslav@1890: * re-acquire the lock associated with this condition. When the jaroslav@1890: * thread returns it is guaranteed to hold this lock. jaroslav@1890: * jaroslav@1890: *
If the current thread: jaroslav@1890: *
Implementation Considerations jaroslav@1890: * jaroslav@1890: *
The current thread is assumed to hold the lock associated with this jaroslav@1890: * {@code Condition} when this method is called. jaroslav@1890: * It is up to the implementation to determine if this is jaroslav@1890: * the case and if not, how to respond. Typically, an exception will be jaroslav@1890: * thrown (such as {@link IllegalMonitorStateException}) and the jaroslav@1890: * implementation must document that fact. jaroslav@1890: * jaroslav@1890: *
An implementation can favor responding to an interrupt over normal jaroslav@1890: * method return in response to a signal. In that case the implementation jaroslav@1890: * must ensure that the signal is redirected to another waiting thread, if jaroslav@1890: * there is one. jaroslav@1890: * jaroslav@1890: * @throws InterruptedException if the current thread is interrupted jaroslav@1890: * (and interruption of thread suspension is supported) jaroslav@1890: */ jaroslav@1890: void await() throws InterruptedException; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Causes the current thread to wait until it is signalled. jaroslav@1890: * jaroslav@1890: *
The lock associated with this condition is atomically jaroslav@1890: * released and the current thread becomes disabled for thread scheduling jaroslav@1890: * purposes and lies dormant until one of three things happens: jaroslav@1890: *
In all cases, before this method can return the current thread must jaroslav@1890: * re-acquire the lock associated with this condition. When the jaroslav@1890: * thread returns it is guaranteed to hold this lock. jaroslav@1890: * jaroslav@1890: *
If the current thread's interrupted status is set when it enters jaroslav@1890: * this method, or it is {@linkplain Thread#interrupt interrupted} jaroslav@1890: * while waiting, it will continue to wait until signalled. When it finally jaroslav@1890: * returns from this method its interrupted status will still jaroslav@1890: * be set. jaroslav@1890: * jaroslav@1890: *
Implementation Considerations jaroslav@1890: * jaroslav@1890: *
The current thread is assumed to hold the lock associated with this jaroslav@1890: * {@code Condition} when this method is called. jaroslav@1890: * It is up to the implementation to determine if this is jaroslav@1890: * the case and if not, how to respond. Typically, an exception will be jaroslav@1890: * thrown (such as {@link IllegalMonitorStateException}) and the jaroslav@1890: * implementation must document that fact. jaroslav@1890: */ jaroslav@1890: void awaitUninterruptibly(); jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Causes the current thread to wait until it is signalled or interrupted, jaroslav@1890: * or the specified waiting time elapses. jaroslav@1890: * jaroslav@1890: *
The lock associated with this condition is atomically jaroslav@1890: * released and the current thread becomes disabled for thread scheduling jaroslav@1890: * purposes and lies dormant until one of five things happens: jaroslav@1890: *
In all cases, before this method can return the current thread must jaroslav@1890: * re-acquire the lock associated with this condition. When the jaroslav@1890: * thread returns it is guaranteed to hold this lock. jaroslav@1890: * jaroslav@1890: *
If the current thread: jaroslav@1890: *
The method returns an estimate of the number of nanoseconds jaroslav@1890: * remaining to wait given the supplied {@code nanosTimeout} jaroslav@1890: * value upon return, or a value less than or equal to zero if it jaroslav@1890: * timed out. This value can be used to determine whether and how jaroslav@1890: * long to re-wait in cases where the wait returns but an awaited jaroslav@1890: * condition still does not hold. Typical uses of this method take jaroslav@1890: * the following form: jaroslav@1890: * jaroslav@1890: *
{@code
jaroslav@1890: * boolean aMethod(long timeout, TimeUnit unit) {
jaroslav@1890: * long nanos = unit.toNanos(timeout);
jaroslav@1890: * lock.lock();
jaroslav@1890: * try {
jaroslav@1890: * while (!conditionBeingWaitedFor()) {
jaroslav@1890: * if (nanos <= 0L)
jaroslav@1890: * return false;
jaroslav@1890: * nanos = theCondition.awaitNanos(nanos);
jaroslav@1890: * }
jaroslav@1890: * // ...
jaroslav@1890: * } finally {
jaroslav@1890: * lock.unlock();
jaroslav@1890: * }
jaroslav@1890: * }}
jaroslav@1890: *
jaroslav@1890: * Design note: This method requires a nanosecond argument so jaroslav@1890: * as to avoid truncation errors in reporting remaining times. jaroslav@1890: * Such precision loss would make it difficult for programmers to jaroslav@1890: * ensure that total waiting times are not systematically shorter jaroslav@1890: * than specified when re-waits occur. jaroslav@1890: * jaroslav@1890: *
Implementation Considerations jaroslav@1890: * jaroslav@1890: *
The current thread is assumed to hold the lock associated with this jaroslav@1890: * {@code Condition} when this method is called. jaroslav@1890: * It is up to the implementation to determine if this is jaroslav@1890: * the case and if not, how to respond. Typically, an exception will be jaroslav@1890: * thrown (such as {@link IllegalMonitorStateException}) and the jaroslav@1890: * implementation must document that fact. jaroslav@1890: * jaroslav@1890: *
An implementation can favor responding to an interrupt over normal
jaroslav@1890: * method return in response to a signal, or over indicating the elapse
jaroslav@1890: * of the specified waiting time. In either case the implementation
jaroslav@1890: * must ensure that the signal is redirected to another waiting thread, if
jaroslav@1890: * there is one.
jaroslav@1890: *
jaroslav@1890: * @param nanosTimeout the maximum time to wait, in nanoseconds
jaroslav@1890: * @return an estimate of the {@code nanosTimeout} value minus
jaroslav@1890: * the time spent waiting upon return from this method.
jaroslav@1890: * A positive value may be used as the argument to a
jaroslav@1890: * subsequent call to this method to finish waiting out
jaroslav@1890: * the desired time. A value less than or equal to zero
jaroslav@1890: * indicates that no time remains.
jaroslav@1890: * @throws InterruptedException if the current thread is interrupted
jaroslav@1890: * (and interruption of thread suspension is supported)
jaroslav@1890: */
jaroslav@1890: long awaitNanos(long nanosTimeout) throws InterruptedException;
jaroslav@1890:
jaroslav@1890: /**
jaroslav@1890: * Causes the current thread to wait until it is signalled or interrupted,
jaroslav@1890: * or the specified waiting time elapses. This method is behaviorally
jaroslav@1890: * equivalent to:
jaroslav@1890: *
jaroslav@1890: * awaitNanos(unit.toNanos(time)) > 0 jaroslav@1890: *jaroslav@1890: * @param time the maximum time to wait jaroslav@1890: * @param unit the time unit of the {@code time} argument jaroslav@1890: * @return {@code false} if the waiting time detectably elapsed jaroslav@1890: * before return from the method, else {@code true} jaroslav@1890: * @throws InterruptedException if the current thread is interrupted jaroslav@1890: * (and interruption of thread suspension is supported) jaroslav@1890: */ jaroslav@1890: boolean await(long time, TimeUnit unit) throws InterruptedException; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Causes the current thread to wait until it is signalled or interrupted, jaroslav@1890: * or the specified deadline elapses. jaroslav@1890: * jaroslav@1890: *
The lock associated with this condition is atomically jaroslav@1890: * released and the current thread becomes disabled for thread scheduling jaroslav@1890: * purposes and lies dormant until one of five things happens: jaroslav@1890: *
In all cases, before this method can return the current thread must jaroslav@1890: * re-acquire the lock associated with this condition. When the jaroslav@1890: * thread returns it is guaranteed to hold this lock. jaroslav@1890: * jaroslav@1890: * jaroslav@1890: *
If the current thread: jaroslav@1890: *
The return value indicates whether the deadline has elapsed, jaroslav@1890: * which can be used as follows: jaroslav@1890: *
{@code
jaroslav@1890: * boolean aMethod(Date deadline) {
jaroslav@1890: * boolean stillWaiting = true;
jaroslav@1890: * lock.lock();
jaroslav@1890: * try {
jaroslav@1890: * while (!conditionBeingWaitedFor()) {
jaroslav@1890: * if (!stillWaiting)
jaroslav@1890: * return false;
jaroslav@1890: * stillWaiting = theCondition.awaitUntil(deadline);
jaroslav@1890: * }
jaroslav@1890: * // ...
jaroslav@1890: * } finally {
jaroslav@1890: * lock.unlock();
jaroslav@1890: * }
jaroslav@1890: * }}
jaroslav@1890: *
jaroslav@1890: * Implementation Considerations jaroslav@1890: * jaroslav@1890: *
The current thread is assumed to hold the lock associated with this jaroslav@1890: * {@code Condition} when this method is called. jaroslav@1890: * It is up to the implementation to determine if this is jaroslav@1890: * the case and if not, how to respond. Typically, an exception will be jaroslav@1890: * thrown (such as {@link IllegalMonitorStateException}) and the jaroslav@1890: * implementation must document that fact. jaroslav@1890: * jaroslav@1890: *
An implementation can favor responding to an interrupt over normal jaroslav@1890: * method return in response to a signal, or over indicating the passing jaroslav@1890: * of the specified deadline. In either case the implementation jaroslav@1890: * must ensure that the signal is redirected to another waiting thread, if jaroslav@1890: * there is one. jaroslav@1890: * jaroslav@1890: * @param deadline the absolute time to wait until jaroslav@1890: * @return {@code false} if the deadline has elapsed upon return, else jaroslav@1890: * {@code true} jaroslav@1890: * @throws InterruptedException if the current thread is interrupted jaroslav@1890: * (and interruption of thread suspension is supported) jaroslav@1890: */ jaroslav@1890: boolean awaitUntil(Date deadline) throws InterruptedException; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Wakes up one waiting thread. jaroslav@1890: * jaroslav@1890: *
If any threads are waiting on this condition then one jaroslav@1890: * is selected for waking up. That thread must then re-acquire the jaroslav@1890: * lock before returning from {@code await}. jaroslav@1890: * jaroslav@1890: *
Implementation Considerations jaroslav@1890: * jaroslav@1890: *
An implementation may (and typically does) require that the jaroslav@1890: * current thread hold the lock associated with this {@code jaroslav@1890: * Condition} when this method is called. Implementations must jaroslav@1890: * document this precondition and any actions taken if the lock is jaroslav@1890: * not held. Typically, an exception such as {@link jaroslav@1890: * IllegalMonitorStateException} will be thrown. jaroslav@1890: */ jaroslav@1890: void signal(); jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Wakes up all waiting threads. jaroslav@1890: * jaroslav@1890: *
If any threads are waiting on this condition then they are jaroslav@1890: * all woken up. Each thread must re-acquire the lock before it can jaroslav@1890: * return from {@code await}. jaroslav@1890: * jaroslav@1890: *
Implementation Considerations jaroslav@1890: * jaroslav@1890: *
An implementation may (and typically does) require that the jaroslav@1890: * current thread hold the lock associated with this {@code jaroslav@1890: * Condition} when this method is called. Implementations must jaroslav@1890: * document this precondition and any actions taken if the lock is jaroslav@1890: * not held. Typically, an exception such as {@link jaroslav@1890: * IllegalMonitorStateException} will be thrown. jaroslav@1890: */ jaroslav@1890: void signalAll(); jaroslav@1890: }