concurrent/locks/Condition.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent.locks;

import java.util.Date;
import java.util.concurrent.TimeUnit;

/**
 * {@code Condition} factors out the {@code Object} monitor
 * methods ({@link Object#wait() wait}, {@link Object#notify notify}
 * and {@link Object#notifyAll notifyAll}) into distinct objects to
 * give the effect of having multiple wait-sets per object, by
 * combining them with the use of arbitrary {@link Lock} implementations.
 * Where a {@code Lock} replaces the use of {@code synchronized} methods
 * and statements, a {@code Condition} replaces the use of the Object
 * monitor methods.
 *
 * <p>Conditions (also known as <em>condition queues</em> or
 * <em>condition variables</em>) provide a means for one thread to
 * suspend execution (to &quot;wait&quot;) until notified by another
 * thread that some state condition may now be true.  Because access
 * to this shared state information occurs in different threads, it
 * must be protected, so a lock of some form is associated with the
 * condition. The key property that waiting for a condition provides
 * is that it <em>atomically</em> releases the associated lock and
 * suspends the current thread, just like {@code Object.wait}.
 *
 * <p>A {@code Condition} instance is intrinsically bound to a lock.
 * To obtain a {@code Condition} instance for a particular {@link Lock}
 * instance use its {@link Lock#newCondition newCondition()} method.
 *
 * <p>As an example, suppose we have a bounded buffer which supports
 * {@code put} and {@code take} methods.  If a
 * {@code take} is attempted on an empty buffer, then the thread will block
 * until an item becomes available; if a {@code put} is attempted on a
 * full buffer, then the thread will block until a space becomes available.
 * We would like to keep waiting {@code put} threads and {@code take}
 * threads in separate wait-sets so that we can use the optimization of
 * only notifying a single thread at a time when items or spaces become
 * available in the buffer. This can be achieved using two
 * {@link Condition} instances.
 * <pre>
 * class BoundedBuffer {
 *   <b>final Lock lock = new ReentrantLock();</b>
 *   final Condition notFull  = <b>lock.newCondition(); </b>
 *   final Condition notEmpty = <b>lock.newCondition(); </b>
 *
 *   final Object[] items = new Object[100];
 *   int putptr, takeptr, count;
 *
 *   public void put(Object x) throws InterruptedException {
 *     <b>lock.lock();
 *     try {</b>
 *       while (count == items.length)
 *         <b>notFull.await();</b>
 *       items[putptr] = x;
 *       if (++putptr == items.length) putptr = 0;
 *       ++count;
 *       <b>notEmpty.signal();</b>
 *     <b>} finally {
 *       lock.unlock();
 *     }</b>
 *   }
 *
 *   public Object take() throws InterruptedException {
 *     <b>lock.lock();
 *     try {</b>
 *       while (count == 0)
 *         <b>notEmpty.await();</b>
 *       Object x = items[takeptr];
 *       if (++takeptr == items.length) takeptr = 0;
 *       --count;
 *       <b>notFull.signal();</b>
 *       return x;
 *     <b>} finally {
 *       lock.unlock();
 *     }</b>
 *   }
 * }
 * </pre>
 *
 * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
 * this functionality, so there is no reason to implement this
 * sample usage class.)
 *
 * <p>A {@code Condition} implementation can provide behavior and semantics
 * that is
 * different from that of the {@code Object} monitor methods, such as
 * guaranteed ordering for notifications, or not requiring a lock to be held
 * when performing notifications.
 * If an implementation provides such specialized semantics then the
 * implementation must document those semantics.
 *
 * <p>Note that {@code Condition} instances are just normal objects and can
 * themselves be used as the target in a {@code synchronized} statement,
 * and can have their own monitor {@link Object#wait wait} and
 * {@link Object#notify notify} methods invoked.
 * Acquiring the monitor lock of a {@code Condition} instance, or using its
 * monitor methods, has no specified relationship with acquiring the
 * {@link Lock} associated with that {@code Condition} or the use of its
 * {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
 * It is recommended that to avoid confusion you never use {@code Condition}
 * instances in this way, except perhaps within their own implementation.
 *
 * <p>Except where noted, passing a {@code null} value for any parameter
 * will result in a {@link NullPointerException} being thrown.
 *
 * <h3>Implementation Considerations</h3>
 *
 * <p>When waiting upon a {@code Condition}, a &quot;<em>spurious
 * wakeup</em>&quot; is permitted to occur, in
 * general, as a concession to the underlying platform semantics.
 * This has little practical impact on most application programs as a
 * {@code Condition} should always be waited upon in a loop, testing
 * the state predicate that is being waited for.  An implementation is
 * free to remove the possibility of spurious wakeups but it is
 * recommended that applications programmers always assume that they can
 * occur and so always wait in a loop.
 *
 * <p>The three forms of condition waiting
 * (interruptible, non-interruptible, and timed) may differ in their ease of
 * implementation on some platforms and in their performance characteristics.
 * In particular, it may be difficult to provide these features and maintain
 * specific semantics such as ordering guarantees.
 * Further, the ability to interrupt the actual suspension of the thread may
 * not always be feasible to implement on all platforms.
 *
 * <p>Consequently, an implementation is not required to define exactly the
 * same guarantees or semantics for all three forms of waiting, nor is it
 * required to support interruption of the actual suspension of the thread.
 *
 * <p>An implementation is required to
 * clearly document the semantics and guarantees provided by each of the
 * waiting methods, and when an implementation does support interruption of
 * thread suspension then it must obey the interruption semantics as defined
 * in this interface.
 *
 * <p>As interruption generally implies cancellation, and checks for
 * interruption are often infrequent, an implementation can favor responding
 * to an interrupt over normal method return. This is true even if it can be
 * shown that the interrupt occurred after another action that may have
 * unblocked the thread. An implementation should document this behavior.
 *
 * @since 1.5
 * @author Doug Lea
 */
public interface Condition {

    /**
     * Causes the current thread to wait until it is signalled or
     * {@linkplain Thread#interrupt interrupted}.
     *
     * <p>The lock associated with this {@code Condition} is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of four things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread invokes the {@link #signalAll} method for this
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
     * </ul>
     *
     * <p>In all cases, before this method can return the current thread must
     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or
     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared. It is not specified, in the first
     * case, whether or not the test for interruption occurs before the lock
     * is released.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     *
     * <p>An implementation can favor responding to an interrupt over normal
     * method return in response to a signal. In that case the implementation
     * must ensure that the signal is redirected to another waiting thread, if
     * there is one.
     *
     * @throws InterruptedException if the current thread is interrupted
     *         (and interruption of thread suspension is supported)
     */
    void await() throws InterruptedException;

    /**
     * Causes the current thread to wait until it is signalled.
     *
     * <p>The lock associated with this condition is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of three things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread invokes the {@link #signalAll} method for this
     * {@code Condition}; or
     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
     * </ul>
     *
     * <p>In all cases, before this method can return the current thread must
     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     * <p>If the current thread's interrupted status is set when it enters
     * this method, or it is {@linkplain Thread#interrupt interrupted}
     * while waiting, it will continue to wait until signalled. When it finally
     * returns from this method its interrupted status will still
     * be set.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     */
    void awaitUninterruptibly();

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified waiting time elapses.
     *
     * <p>The lock associated with this condition is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of five things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread invokes the {@link #signalAll} method for this
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>The specified waiting time elapses; or
     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
     * </ul>
     *
     * <p>In all cases, before this method can return the current thread must
     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or
     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared. It is not specified, in the first
     * case, whether or not the test for interruption occurs before the lock
     * is released.
     *
     * <p>The method returns an estimate of the number of nanoseconds
     * remaining to wait given the supplied {@code nanosTimeout}
     * value upon return, or a value less than or equal to zero if it
     * timed out. This value can be used to determine whether and how
     * long to re-wait in cases where the wait returns but an awaited
     * condition still does not hold. Typical uses of this method take
     * the following form:
     *
     * <pre> {@code
     * boolean aMethod(long timeout, TimeUnit unit) {
     *   long nanos = unit.toNanos(timeout);
     *   lock.lock();
     *   try {
     *     while (!conditionBeingWaitedFor()) {
     *       if (nanos <= 0L)
     *         return false;
     *       nanos = theCondition.awaitNanos(nanos);
     *     }
     *     // ...
     *   } finally {
     *     lock.unlock();
     *   }
     * }}</pre>
     *
     * <p>Design note: This method requires a nanosecond argument so
     * as to avoid truncation errors in reporting remaining times.
     * Such precision loss would make it difficult for programmers to
     * ensure that total waiting times are not systematically shorter
     * than specified when re-waits occur.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     *
     * <p>An implementation can favor responding to an interrupt over normal
     * method return in response to a signal, or over indicating the elapse
     * of the specified waiting time. In either case the implementation
     * must ensure that the signal is redirected to another waiting thread, if
     * there is one.
     *
     * @param nanosTimeout the maximum time to wait, in nanoseconds
     * @return an estimate of the {@code nanosTimeout} value minus
     *         the time spent waiting upon return from this method.
     *         A positive value may be used as the argument to a
     *         subsequent call to this method to finish waiting out
     *         the desired time.  A value less than or equal to zero
     *         indicates that no time remains.
     * @throws InterruptedException if the current thread is interrupted
     *         (and interruption of thread suspension is supported)
     */
    long awaitNanos(long nanosTimeout) throws InterruptedException;

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified waiting time elapses. This method is behaviorally
     * equivalent to:
     * <pre> {@code awaitNanos(unit.toNanos(time)) > 0}</pre>
     *
     * @param time the maximum time to wait
     * @param unit the time unit of the {@code time} argument
     * @return {@code false} if the waiting time detectably elapsed
     *         before return from the method, else {@code true}
     * @throws InterruptedException if the current thread is interrupted
     *         (and interruption of thread suspension is supported)
     */
    boolean await(long time, TimeUnit unit) throws InterruptedException;

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified deadline elapses.
     *
     * <p>The lock associated with this condition is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of five things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread invokes the {@link #signalAll} method for this
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>The specified deadline elapses; or
     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
     * </ul>
     *
     * <p>In all cases, before this method can return the current thread must
     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or
     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared. It is not specified, in the first
     * case, whether or not the test for interruption occurs before the lock
     * is released.
     *
     * <p>The return value indicates whether the deadline has elapsed,
     * which can be used as follows:
     * <pre> {@code
     * boolean aMethod(Date deadline) {
     *   boolean stillWaiting = true;
     *   lock.lock();
     *   try {
     *     while (!conditionBeingWaitedFor()) {
     *       if (!stillWaiting)
     *         return false;
     *       stillWaiting = theCondition.awaitUntil(deadline);
     *     }
     *     // ...
     *   } finally {
     *     lock.unlock();
     *   }
     * }}</pre>
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     *
     * <p>An implementation can favor responding to an interrupt over normal
     * method return in response to a signal, or over indicating the passing
     * of the specified deadline. In either case the implementation
     * must ensure that the signal is redirected to another waiting thread, if
     * there is one.
     *
     * @param deadline the absolute time to wait until
     * @return {@code false} if the deadline has elapsed upon return, else
     *         {@code true}
     * @throws InterruptedException if the current thread is interrupted
     *         (and interruption of thread suspension is supported)
     */
    boolean awaitUntil(Date deadline) throws InterruptedException;

    /**
     * Wakes up one waiting thread.
     *
     * <p>If any threads are waiting on this condition then one
     * is selected for waking up. That thread must then re-acquire the
     * lock before returning from {@code await}.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>An implementation may (and typically does) require that the
     * current thread hold the lock associated with this {@code
     * Condition} when this method is called. Implementations must
     * document this precondition and any actions taken if the lock is
     * not held. Typically, an exception such as {@link
     * IllegalMonitorStateException} will be thrown.
     */
    void signal();

    /**
     * Wakes up all waiting threads.
     *
     * <p>If any threads are waiting on this condition then they are
     * all woken up. Each thread must re-acquire the lock before it can
     * return from {@code await}.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>An implementation may (and typically does) require that the
     * current thread hold the lock associated with this {@code
     * Condition} when this method is called. Implementations must
     * document this precondition and any actions taken if the lock is
     * not held. Typically, an exception such as {@link
     * IllegalMonitorStateException} will be thrown.
     */
    void signalAll();
}
Revision:	1.2
Committed:	Fri Jul 8 20:02:54 2016 UTC (7 years, 10 months ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+0 -2 lines
Log Message:	whitespace
#	Content
1	/*
2	* Written by Doug Lea with assistance from members of JCP JSR-166
3	* Expert Group and released to the public domain, as explained at
4	* http://creativecommons.org/publicdomain/zero/1.0/
5	*/
6
7	package java.util.concurrent.locks;
8
9	import java.util.Date;
10	import java.util.concurrent.TimeUnit;
11
12	/**
13	* {@code Condition} factors out the {@code Object} monitor
14	* methods ({@link Object#wait() wait}, {@link Object#notify notify}
15	* and {@link Object#notifyAll notifyAll}) into distinct objects to
16	* give the effect of having multiple wait-sets per object, by
17	* combining them with the use of arbitrary {@link Lock} implementations.
18	* Where a {@code Lock} replaces the use of {@code synchronized} methods
19	* and statements, a {@code Condition} replaces the use of the Object
20	* monitor methods.
21	*
22	* <p>Conditions (also known as <em>condition queues</em> or
23	* <em>condition variables</em>) provide a means for one thread to
24	* suspend execution (to "wait") until notified by another
25	* thread that some state condition may now be true. Because access
26	* to this shared state information occurs in different threads, it
27	* must be protected, so a lock of some form is associated with the
28	* condition. The key property that waiting for a condition provides
29	* is that it <em>atomically</em> releases the associated lock and
30	* suspends the current thread, just like {@code Object.wait}.
31	*
32	* <p>A {@code Condition} instance is intrinsically bound to a lock.
33	* To obtain a {@code Condition} instance for a particular {@link Lock}
34	* instance use its {@link Lock#newCondition newCondition()} method.
35	*
36	* <p>As an example, suppose we have a bounded buffer which supports
37	* {@code put} and {@code take} methods. If a
38	* {@code take} is attempted on an empty buffer, then the thread will block
39	* until an item becomes available; if a {@code put} is attempted on a
40	* full buffer, then the thread will block until a space becomes available.
41	* We would like to keep waiting {@code put} threads and {@code take}
42	* threads in separate wait-sets so that we can use the optimization of
43	* only notifying a single thread at a time when items or spaces become
44	* available in the buffer. This can be achieved using two
45	* {@link Condition} instances.
46	* <pre>
47	* class BoundedBuffer {
48	* <b>final Lock lock = new ReentrantLock();</b>
49	* final Condition notFull = <b>lock.newCondition(); </b>
50	* final Condition notEmpty = <b>lock.newCondition(); </b>
51	*
52	* final Object[] items = new Object[100];
53	* int putptr, takeptr, count;
54	*
55	* public void put(Object x) throws InterruptedException {
56	* <b>lock.lock();
57	* try {</b>
58	* while (count == items.length)
59	* <b>notFull.await();</b>
60	* items[putptr] = x;
61	* if (++putptr == items.length) putptr = 0;
62	* ++count;
63	* <b>notEmpty.signal();</b>
64	* <b>} finally {
65	* lock.unlock();
66	* }</b>
67	* }
68	*
69	* public Object take() throws InterruptedException {
70	* <b>lock.lock();
71	* try {</b>
72	* while (count == 0)
73	* <b>notEmpty.await();</b>
74	* Object x = items[takeptr];
75	* if (++takeptr == items.length) takeptr = 0;
76	* --count;
77	* <b>notFull.signal();</b>
78	* return x;
79	* <b>} finally {
80	* lock.unlock();
81	* }</b>
82	* }
83	* }
84	* </pre>
85	*
86	* (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
87	* this functionality, so there is no reason to implement this
88	* sample usage class.)
89	*
90	* <p>A {@code Condition} implementation can provide behavior and semantics
91	* that is
92	* different from that of the {@code Object} monitor methods, such as
93	* guaranteed ordering for notifications, or not requiring a lock to be held
94	* when performing notifications.
95	* If an implementation provides such specialized semantics then the
96	* implementation must document those semantics.
97	*
98	* <p>Note that {@code Condition} instances are just normal objects and can
99	* themselves be used as the target in a {@code synchronized} statement,
100	* and can have their own monitor {@link Object#wait wait} and
101	* {@link Object#notify notify} methods invoked.
102	* Acquiring the monitor lock of a {@code Condition} instance, or using its
103	* monitor methods, has no specified relationship with acquiring the
104	* {@link Lock} associated with that {@code Condition} or the use of its
105	* {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
106	* It is recommended that to avoid confusion you never use {@code Condition}
107	* instances in this way, except perhaps within their own implementation.
108	*
109	* <p>Except where noted, passing a {@code null} value for any parameter
110	* will result in a {@link NullPointerException} being thrown.
111	*
112	* <h3>Implementation Considerations</h3>
113	*
114	* <p>When waiting upon a {@code Condition}, a "<em>spurious
115	* wakeup</em>" is permitted to occur, in
116	* general, as a concession to the underlying platform semantics.
117	* This has little practical impact on most application programs as a
118	* {@code Condition} should always be waited upon in a loop, testing
119	* the state predicate that is being waited for. An implementation is
120	* free to remove the possibility of spurious wakeups but it is
121	* recommended that applications programmers always assume that they can
122	* occur and so always wait in a loop.
123	*
124	* <p>The three forms of condition waiting
125	* (interruptible, non-interruptible, and timed) may differ in their ease of
126	* implementation on some platforms and in their performance characteristics.
127	* In particular, it may be difficult to provide these features and maintain
128	* specific semantics such as ordering guarantees.
129	* Further, the ability to interrupt the actual suspension of the thread may
130	* not always be feasible to implement on all platforms.
131	*
132	* <p>Consequently, an implementation is not required to define exactly the
133	* same guarantees or semantics for all three forms of waiting, nor is it
134	* required to support interruption of the actual suspension of the thread.
135	*
136	* <p>An implementation is required to
137	* clearly document the semantics and guarantees provided by each of the
138	* waiting methods, and when an implementation does support interruption of
139	* thread suspension then it must obey the interruption semantics as defined
140	* in this interface.
141	*
142	* <p>As interruption generally implies cancellation, and checks for
143	* interruption are often infrequent, an implementation can favor responding
144	* to an interrupt over normal method return. This is true even if it can be
145	* shown that the interrupt occurred after another action that may have
146	* unblocked the thread. An implementation should document this behavior.
147	*
148	* @since 1.5
149	* @author Doug Lea
150	*/
151	public interface Condition {
152
153	/**
154	* Causes the current thread to wait until it is signalled or
155	* {@linkplain Thread#interrupt interrupted}.
156	*
157	* <p>The lock associated with this {@code Condition} is atomically
158	* released and the current thread becomes disabled for thread scheduling
159	* purposes and lies dormant until <em>one</em> of four things happens:
160	* <ul>
161	* <li>Some other thread invokes the {@link #signal} method for this
162	* {@code Condition} and the current thread happens to be chosen as the
163	* thread to be awakened; or
164	* <li>Some other thread invokes the {@link #signalAll} method for this
165	* {@code Condition}; or
166	* <li>Some other thread {@linkplain Thread#interrupt interrupts} the
167	* current thread, and interruption of thread suspension is supported; or
168	* <li>A "<em>spurious wakeup</em>" occurs.
169	* </ul>
170	*
171	* <p>In all cases, before this method can return the current thread must
172	* re-acquire the lock associated with this condition. When the
173	* thread returns it is <em>guaranteed</em> to hold this lock.
174	*
175	* <p>If the current thread:
176	* <ul>
177	* <li>has its interrupted status set on entry to this method; or
178	* <li>is {@linkplain Thread#interrupt interrupted} while waiting
179	* and interruption of thread suspension is supported,
180	* </ul>
181	* then {@link InterruptedException} is thrown and the current thread's
182	* interrupted status is cleared. It is not specified, in the first
183	* case, whether or not the test for interruption occurs before the lock
184	* is released.
185	*
186	* <p><b>Implementation Considerations</b>
187	*
188	* <p>The current thread is assumed to hold the lock associated with this
189	* {@code Condition} when this method is called.
190	* It is up to the implementation to determine if this is
191	* the case and if not, how to respond. Typically, an exception will be
192	* thrown (such as {@link IllegalMonitorStateException}) and the
193	* implementation must document that fact.
194	*
195	* <p>An implementation can favor responding to an interrupt over normal
196	* method return in response to a signal. In that case the implementation
197	* must ensure that the signal is redirected to another waiting thread, if
198	* there is one.
199	*
200	* @throws InterruptedException if the current thread is interrupted
201	* (and interruption of thread suspension is supported)
202	*/
203	void await() throws InterruptedException;
204
205	/**
206	* Causes the current thread to wait until it is signalled.
207	*
208	* <p>The lock associated with this condition is atomically
209	* released and the current thread becomes disabled for thread scheduling
210	* purposes and lies dormant until <em>one</em> of three things happens:
211	* <ul>
212	* <li>Some other thread invokes the {@link #signal} method for this
213	* {@code Condition} and the current thread happens to be chosen as the
214	* thread to be awakened; or
215	* <li>Some other thread invokes the {@link #signalAll} method for this
216	* {@code Condition}; or
217	* <li>A "<em>spurious wakeup</em>" occurs.
218	* </ul>
219	*
220	* <p>In all cases, before this method can return the current thread must
221	* re-acquire the lock associated with this condition. When the
222	* thread returns it is <em>guaranteed</em> to hold this lock.
223	*
224	* <p>If the current thread's interrupted status is set when it enters
225	* this method, or it is {@linkplain Thread#interrupt interrupted}
226	* while waiting, it will continue to wait until signalled. When it finally
227	* returns from this method its interrupted status will still
228	* be set.
229	*
230	* <p><b>Implementation Considerations</b>
231	*
232	* <p>The current thread is assumed to hold the lock associated with this
233	* {@code Condition} when this method is called.
234	* It is up to the implementation to determine if this is
235	* the case and if not, how to respond. Typically, an exception will be
236	* thrown (such as {@link IllegalMonitorStateException}) and the
237	* implementation must document that fact.
238	*/
239	void awaitUninterruptibly();
240
241	/**
242	* Causes the current thread to wait until it is signalled or interrupted,
243	* or the specified waiting time elapses.
244	*
245	* <p>The lock associated with this condition is atomically
246	* released and the current thread becomes disabled for thread scheduling
247	* purposes and lies dormant until <em>one</em> of five things happens:
248	* <ul>
249	* <li>Some other thread invokes the {@link #signal} method for this
250	* {@code Condition} and the current thread happens to be chosen as the
251	* thread to be awakened; or
252	* <li>Some other thread invokes the {@link #signalAll} method for this
253	* {@code Condition}; or
254	* <li>Some other thread {@linkplain Thread#interrupt interrupts} the
255	* current thread, and interruption of thread suspension is supported; or
256	* <li>The specified waiting time elapses; or
257	* <li>A "<em>spurious wakeup</em>" occurs.
258	* </ul>
259	*
260	* <p>In all cases, before this method can return the current thread must
261	* re-acquire the lock associated with this condition. When the
262	* thread returns it is <em>guaranteed</em> to hold this lock.
263	*
264	* <p>If the current thread:
265	* <ul>
266	* <li>has its interrupted status set on entry to this method; or
267	* <li>is {@linkplain Thread#interrupt interrupted} while waiting
268	* and interruption of thread suspension is supported,
269	* </ul>
270	* then {@link InterruptedException} is thrown and the current thread's
271	* interrupted status is cleared. It is not specified, in the first
272	* case, whether or not the test for interruption occurs before the lock
273	* is released.
274	*
275	* <p>The method returns an estimate of the number of nanoseconds
276	* remaining to wait given the supplied {@code nanosTimeout}
277	* value upon return, or a value less than or equal to zero if it
278	* timed out. This value can be used to determine whether and how
279	* long to re-wait in cases where the wait returns but an awaited
280	* condition still does not hold. Typical uses of this method take
281	* the following form:
282	*
283	* <pre> {@code
284	* boolean aMethod(long timeout, TimeUnit unit) {
285	* long nanos = unit.toNanos(timeout);
286	* lock.lock();
287	* try {
288	* while (!conditionBeingWaitedFor()) {
289	* if (nanos <= 0L)
290	* return false;
291	* nanos = theCondition.awaitNanos(nanos);
292	* }
293	* // ...
294	* } finally {
295	* lock.unlock();
296	* }
297	* }}</pre>
298	*
299	* <p>Design note: This method requires a nanosecond argument so
300	* as to avoid truncation errors in reporting remaining times.
301	* Such precision loss would make it difficult for programmers to
302	* ensure that total waiting times are not systematically shorter
303	* than specified when re-waits occur.
304	*
305	* <p><b>Implementation Considerations</b>
306	*
307	* <p>The current thread is assumed to hold the lock associated with this
308	* {@code Condition} when this method is called.
309	* It is up to the implementation to determine if this is
310	* the case and if not, how to respond. Typically, an exception will be
311	* thrown (such as {@link IllegalMonitorStateException}) and the
312	* implementation must document that fact.
313	*
314	* <p>An implementation can favor responding to an interrupt over normal
315	* method return in response to a signal, or over indicating the elapse
316	* of the specified waiting time. In either case the implementation
317	* must ensure that the signal is redirected to another waiting thread, if
318	* there is one.
319	*
320	* @param nanosTimeout the maximum time to wait, in nanoseconds
321	* @return an estimate of the {@code nanosTimeout} value minus
322	* the time spent waiting upon return from this method.
323	* A positive value may be used as the argument to a
324	* subsequent call to this method to finish waiting out
325	* the desired time. A value less than or equal to zero
326	* indicates that no time remains.
327	* @throws InterruptedException if the current thread is interrupted
328	* (and interruption of thread suspension is supported)
329	*/
330	long awaitNanos(long nanosTimeout) throws InterruptedException;
331
332	/**
333	* Causes the current thread to wait until it is signalled or interrupted,
334	* or the specified waiting time elapses. This method is behaviorally
335	* equivalent to:
336	* <pre> {@code awaitNanos(unit.toNanos(time)) > 0}</pre>
337	*
338	* @param time the maximum time to wait
339	* @param unit the time unit of the {@code time} argument
340	* @return {@code false} if the waiting time detectably elapsed
341	* before return from the method, else {@code true}
342	* @throws InterruptedException if the current thread is interrupted
343	* (and interruption of thread suspension is supported)
344	*/
345	boolean await(long time, TimeUnit unit) throws InterruptedException;
346
347	/**
348	* Causes the current thread to wait until it is signalled or interrupted,
349	* or the specified deadline elapses.
350	*
351	* <p>The lock associated with this condition is atomically
352	* released and the current thread becomes disabled for thread scheduling
353	* purposes and lies dormant until <em>one</em> of five things happens:
354	* <ul>
355	* <li>Some other thread invokes the {@link #signal} method for this
356	* {@code Condition} and the current thread happens to be chosen as the
357	* thread to be awakened; or
358	* <li>Some other thread invokes the {@link #signalAll} method for this
359	* {@code Condition}; or
360	* <li>Some other thread {@linkplain Thread#interrupt interrupts} the
361	* current thread, and interruption of thread suspension is supported; or
362	* <li>The specified deadline elapses; or
363	* <li>A "<em>spurious wakeup</em>" occurs.
364	* </ul>
365	*
366	* <p>In all cases, before this method can return the current thread must
367	* re-acquire the lock associated with this condition. When the
368	* thread returns it is <em>guaranteed</em> to hold this lock.
369	*
370	* <p>If the current thread:
371	* <ul>
372	* <li>has its interrupted status set on entry to this method; or
373	* <li>is {@linkplain Thread#interrupt interrupted} while waiting
374	* and interruption of thread suspension is supported,
375	* </ul>
376	* then {@link InterruptedException} is thrown and the current thread's
377	* interrupted status is cleared. It is not specified, in the first
378	* case, whether or not the test for interruption occurs before the lock
379	* is released.
380	*
381	* <p>The return value indicates whether the deadline has elapsed,
382	* which can be used as follows:
383	* <pre> {@code
384	* boolean aMethod(Date deadline) {
385	* boolean stillWaiting = true;
386	* lock.lock();
387	* try {
388	* while (!conditionBeingWaitedFor()) {
389	* if (!stillWaiting)
390	* return false;
391	* stillWaiting = theCondition.awaitUntil(deadline);
392	* }
393	* // ...
394	* } finally {
395	* lock.unlock();
396	* }
397	* }}</pre>
398	*
399	* <p><b>Implementation Considerations</b>
400	*
401	* <p>The current thread is assumed to hold the lock associated with this
402	* {@code Condition} when this method is called.
403	* It is up to the implementation to determine if this is
404	* the case and if not, how to respond. Typically, an exception will be
405	* thrown (such as {@link IllegalMonitorStateException}) and the
406	* implementation must document that fact.
407	*
408	* <p>An implementation can favor responding to an interrupt over normal
409	* method return in response to a signal, or over indicating the passing
410	* of the specified deadline. In either case the implementation
411	* must ensure that the signal is redirected to another waiting thread, if
412	* there is one.
413	*
414	* @param deadline the absolute time to wait until
415	* @return {@code false} if the deadline has elapsed upon return, else
416	* {@code true}
417	* @throws InterruptedException if the current thread is interrupted
418	* (and interruption of thread suspension is supported)
419	*/
420	boolean awaitUntil(Date deadline) throws InterruptedException;
421
422	/**
423	* Wakes up one waiting thread.
424	*
425	* <p>If any threads are waiting on this condition then one
426	* is selected for waking up. That thread must then re-acquire the
427	* lock before returning from {@code await}.
428	*
429	* <p><b>Implementation Considerations</b>
430	*
431	* <p>An implementation may (and typically does) require that the
432	* current thread hold the lock associated with this {@code
433	* Condition} when this method is called. Implementations must
434	* document this precondition and any actions taken if the lock is
435	* not held. Typically, an exception such as {@link
436	* IllegalMonitorStateException} will be thrown.
437	*/
438	void signal();
439
440	/**
441	* Wakes up all waiting threads.
442	*
443	* <p>If any threads are waiting on this condition then they are
444	* all woken up. Each thread must re-acquire the lock before it can
445	* return from {@code await}.
446	*
447	* <p><b>Implementation Considerations</b>
448	*
449	* <p>An implementation may (and typically does) require that the
450	* current thread hold the lock associated with this {@code
451	* Condition} when this method is called. Implementations must
452	* document this precondition and any actions taken if the lock is
453	* not held. Typically, an exception such as {@link
454	* IllegalMonitorStateException} will be thrown.
455	*/
456	void signalAll();
457	}