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/licenses/publicdomain
7 package java.util.concurrent.locks;
8 import java.util.concurrent.*;
12 * {@code Condition} factors out the {@code Object} monitor
13 * methods ({@link Object#wait() wait}, {@link Object#notify notify}
14 * and {@link Object#notifyAll notifyAll}) into distinct objects to
15 * give the effect of having multiple wait-sets per object, by
16 * combining them with the use of arbitrary {@link Lock} implementations.
17 * Where a {@code Lock} replaces the use of {@code synchronized} methods
18 * and statements, a {@code Condition} replaces the use of the Object
21 * <p>Conditions (also known as <em>condition queues</em> or
22 * <em>condition variables</em>) provide a means for one thread to
23 * suspend execution (to "wait") until notified by another
24 * thread that some state condition may now be true. Because access
25 * to this shared state information occurs in different threads, it
26 * must be protected, so a lock of some form is associated with the
27 * condition. The key property that waiting for a condition provides
28 * is that it <em>atomically</em> releases the associated lock and
29 * suspends the current thread, just like {@code Object.wait}.
31 * <p>A {@code Condition} instance is intrinsically bound to a lock.
32 * To obtain a {@code Condition} instance for a particular {@link Lock}
33 * instance use its {@link Lock#newCondition newCondition()} method.
35 * <p>As an example, suppose we have a bounded buffer which supports
36 * {@code put} and {@code take} methods. If a
37 * {@code take} is attempted on an empty buffer, then the thread will block
38 * until an item becomes available; if a {@code put} is attempted on a
39 * full buffer, then the thread will block until a space becomes available.
40 * We would like to keep waiting {@code put} threads and {@code take}
41 * threads in separate wait-sets so that we can use the optimization of
42 * only notifying a single thread at a time when items or spaces become
43 * available in the buffer. This can be achieved using two
44 * {@link Condition} instances.
46 * class BoundedBuffer {
47 * <b>final Lock lock = new ReentrantLock();</b>
48 * final Condition notFull = <b>lock.newCondition(); </b>
49 * final Condition notEmpty = <b>lock.newCondition(); </b>
51 * final Object[] items = new Object[100];
52 * int putptr, takeptr, count;
54 * public void put(Object x) throws InterruptedException {
57 * while (count == items.length)
58 * <b>notFull.await();</b>
60 * if (++putptr == items.length) putptr = 0;
62 * <b>notEmpty.signal();</b>
68 * public Object take() throws InterruptedException {
72 * <b>notEmpty.await();</b>
73 * Object x = items[takeptr];
74 * if (++takeptr == items.length) takeptr = 0;
76 * <b>notFull.signal();</b>
85 * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
86 * this functionality, so there is no reason to implement this
87 * sample usage class.)
89 * <p>A {@code Condition} implementation can provide behavior and semantics
91 * different from that of the {@code Object} monitor methods, such as
92 * guaranteed ordering for notifications, or not requiring a lock to be held
93 * when performing notifications.
94 * If an implementation provides such specialized semantics then the
95 * implementation must document those semantics.
97 * <p>Note that {@code Condition} instances are just normal objects and can
98 * themselves be used as the target in a {@code synchronized} statement,
99 * and can have their own monitor {@link Object#wait wait} and
100 * {@link Object#notify notification} methods invoked.
101 * Acquiring the monitor lock of a {@code Condition} instance, or using its
102 * monitor methods, has no specified relationship with acquiring the
103 * {@link Lock} associated with that {@code Condition} or the use of its
104 * {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
105 * It is recommended that to avoid confusion you never use {@code Condition}
106 * instances in this way, except perhaps within their own implementation.
108 * <p>Except where noted, passing a {@code null} value for any parameter
109 * will result in a {@link NullPointerException} being thrown.
111 * <h3>Implementation Considerations</h3>
113 * <p>When waiting upon a {@code Condition}, a "<em>spurious
114 * wakeup</em>" is permitted to occur, in
115 * general, as a concession to the underlying platform semantics.
116 * This has little practical impact on most application programs as a
117 * {@code Condition} should always be waited upon in a loop, testing
118 * the state predicate that is being waited for. An implementation is
119 * free to remove the possibility of spurious wakeups but it is
120 * recommended that applications programmers always assume that they can
121 * occur and so always wait in a loop.
123 * <p>The three forms of condition waiting
124 * (interruptible, non-interruptible, and timed) may differ in their ease of
125 * implementation on some platforms and in their performance characteristics.
126 * In particular, it may be difficult to provide these features and maintain
127 * specific semantics such as ordering guarantees.
128 * Further, the ability to interrupt the actual suspension of the thread may
129 * not always be feasible to implement on all platforms.
131 * <p>Consequently, an implementation is not required to define exactly the
132 * same guarantees or semantics for all three forms of waiting, nor is it
133 * required to support interruption of the actual suspension of the thread.
135 * <p>An implementation is required to
136 * clearly document the semantics and guarantees provided by each of the
137 * waiting methods, and when an implementation does support interruption of
138 * thread suspension then it must obey the interruption semantics as defined
141 * <p>As interruption generally implies cancellation, and checks for
142 * interruption are often infrequent, an implementation can favor responding
143 * to an interrupt over normal method return. This is true even if it can be
144 * shown that the interrupt occurred after another action may have unblocked
145 * the thread. An implementation should document this behavior.
150 public interface Condition {
153 * Causes the current thread to wait until it is signalled or
154 * {@linkplain Thread#interrupt interrupted}.
156 * <p>The lock associated with this {@code Condition} is atomically
157 * released and the current thread becomes disabled for thread scheduling
158 * purposes and lies dormant until <em>one</em> of four things happens:
160 * <li>Some other thread invokes the {@link #signal} method for this
161 * {@code Condition} and the current thread happens to be chosen as the
162 * thread to be awakened; or
163 * <li>Some other thread invokes the {@link #signalAll} method for this
164 * {@code Condition}; or
165 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
166 * current thread, and interruption of thread suspension is supported; or
167 * <li>A "<em>spurious wakeup</em>" occurs.
170 * <p>In all cases, before this method can return the current thread must
171 * re-acquire the lock associated with this condition. When the
172 * thread returns it is <em>guaranteed</em> to hold this lock.
174 * <p>If the current thread:
176 * <li>has its interrupted status set on entry to this method; or
177 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
178 * and interruption of thread suspension is supported,
180 * then {@link InterruptedException} is thrown and the current thread's
181 * interrupted status is cleared. It is not specified, in the first
182 * case, whether or not the test for interruption occurs before the lock
185 * <p><b>Implementation Considerations</b>
187 * <p>The current thread is assumed to hold the lock associated with this
188 * {@code Condition} when this method is called.
189 * It is up to the implementation to determine if this is
190 * the case and if not, how to respond. Typically, an exception will be
191 * thrown (such as {@link IllegalMonitorStateException}) and the
192 * implementation must document that fact.
194 * <p>An implementation can favor responding to an interrupt over normal
195 * method return in response to a signal. In that case the implementation
196 * must ensure that the signal is redirected to another waiting thread, if
199 * @throws InterruptedException if the current thread is interrupted
200 * (and interruption of thread suspension is supported)
202 void await() throws InterruptedException;
205 * Causes the current thread to wait until it is signalled.
207 * <p>The lock associated with this condition is atomically
208 * released and the current thread becomes disabled for thread scheduling
209 * purposes and lies dormant until <em>one</em> of three things happens:
211 * <li>Some other thread invokes the {@link #signal} method for this
212 * {@code Condition} and the current thread happens to be chosen as the
213 * thread to be awakened; or
214 * <li>Some other thread invokes the {@link #signalAll} method for this
215 * {@code Condition}; or
216 * <li>A "<em>spurious wakeup</em>" occurs.
219 * <p>In all cases, before this method can return the current thread must
220 * re-acquire the lock associated with this condition. When the
221 * thread returns it is <em>guaranteed</em> to hold this lock.
223 * <p>If the current thread's interrupted status is set when it enters
224 * this method, or it is {@linkplain Thread#interrupt interrupted}
225 * while waiting, it will continue to wait until signalled. When it finally
226 * returns from this method its interrupted status will still
229 * <p><b>Implementation Considerations</b>
231 * <p>The current thread is assumed to hold the lock associated with this
232 * {@code Condition} when this method is called.
233 * It is up to the implementation to determine if this is
234 * the case and if not, how to respond. Typically, an exception will be
235 * thrown (such as {@link IllegalMonitorStateException}) and the
236 * implementation must document that fact.
238 void awaitUninterruptibly();
241 * Causes the current thread to wait until it is signalled or interrupted,
242 * or the specified waiting time elapses.
244 * <p>The lock associated with this condition is atomically
245 * released and the current thread becomes disabled for thread scheduling
246 * purposes and lies dormant until <em>one</em> of five things happens:
248 * <li>Some other thread invokes the {@link #signal} method for this
249 * {@code Condition} and the current thread happens to be chosen as the
250 * thread to be awakened; or
251 * <li>Some other thread invokes the {@link #signalAll} method for this
252 * {@code Condition}; or
253 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
254 * current thread, and interruption of thread suspension is supported; or
255 * <li>The specified waiting time elapses; or
256 * <li>A "<em>spurious wakeup</em>" occurs.
259 * <p>In all cases, before this method can return the current thread must
260 * re-acquire the lock associated with this condition. When the
261 * thread returns it is <em>guaranteed</em> to hold this lock.
263 * <p>If the current thread:
265 * <li>has its interrupted status set on entry to this method; or
266 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
267 * and interruption of thread suspension is supported,
269 * then {@link InterruptedException} is thrown and the current thread's
270 * interrupted status is cleared. It is not specified, in the first
271 * case, whether or not the test for interruption occurs before the lock
274 * <p>The method returns an estimate of the number of nanoseconds
275 * remaining to wait given the supplied {@code nanosTimeout}
276 * value upon return, or a value less than or equal to zero if it
277 * timed out. This value can be used to determine whether and how
278 * long to re-wait in cases where the wait returns but an awaited
279 * condition still does not hold. Typical uses of this method take
280 * the following form:
283 * synchronized boolean aMethod(long timeout, TimeUnit unit) {
284 * long nanosTimeout = unit.toNanos(timeout);
285 * while (!conditionBeingWaitedFor) {
286 * if (nanosTimeout > 0)
287 * nanosTimeout = theCondition.awaitNanos(nanosTimeout);
295 * <p> Design note: This method requires a nanosecond argument so
296 * as to avoid truncation errors in reporting remaining times.
297 * Such precision loss would make it difficult for programmers to
298 * ensure that total waiting times are not systematically shorter
299 * than specified when re-waits occur.
301 * <p><b>Implementation Considerations</b>
303 * <p>The current thread is assumed to hold the lock associated with this
304 * {@code Condition} when this method is called.
305 * It is up to the implementation to determine if this is
306 * the case and if not, how to respond. Typically, an exception will be
307 * thrown (such as {@link IllegalMonitorStateException}) and the
308 * implementation must document that fact.
310 * <p>An implementation can favor responding to an interrupt over normal
311 * method return in response to a signal, or over indicating the elapse
312 * of the specified waiting time. In either case the implementation
313 * must ensure that the signal is redirected to another waiting thread, if
316 * @param nanosTimeout the maximum time to wait, in nanoseconds
317 * @return an estimate of the {@code nanosTimeout} value minus
318 * the time spent waiting upon return from this method.
319 * A positive value may be used as the argument to a
320 * subsequent call to this method to finish waiting out
321 * the desired time. A value less than or equal to zero
322 * indicates that no time remains.
323 * @throws InterruptedException if the current thread is interrupted
324 * (and interruption of thread suspension is supported)
326 long awaitNanos(long nanosTimeout) throws InterruptedException;
329 * Causes the current thread to wait until it is signalled or interrupted,
330 * or the specified waiting time elapses. This method is behaviorally
333 * awaitNanos(unit.toNanos(time)) > 0
335 * @param time the maximum time to wait
336 * @param unit the time unit of the {@code time} argument
337 * @return {@code false} if the waiting time detectably elapsed
338 * before return from the method, else {@code true}
339 * @throws InterruptedException if the current thread is interrupted
340 * (and interruption of thread suspension is supported)
342 //boolean await(long time, TimeUnit unit) throws InterruptedException;
345 * Causes the current thread to wait until it is signalled or interrupted,
346 * or the specified deadline elapses.
348 * <p>The lock associated with this condition is atomically
349 * released and the current thread becomes disabled for thread scheduling
350 * purposes and lies dormant until <em>one</em> of five things happens:
352 * <li>Some other thread invokes the {@link #signal} method for this
353 * {@code Condition} and the current thread happens to be chosen as the
354 * thread to be awakened; or
355 * <li>Some other thread invokes the {@link #signalAll} method for this
356 * {@code Condition}; or
357 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
358 * current thread, and interruption of thread suspension is supported; or
359 * <li>The specified deadline elapses; or
360 * <li>A "<em>spurious wakeup</em>" occurs.
363 * <p>In all cases, before this method can return the current thread must
364 * re-acquire the lock associated with this condition. When the
365 * thread returns it is <em>guaranteed</em> to hold this lock.
368 * <p>If the current thread:
370 * <li>has its interrupted status set on entry to this method; or
371 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
372 * and interruption of thread suspension is supported,
374 * then {@link InterruptedException} is thrown and the current thread's
375 * interrupted status is cleared. It is not specified, in the first
376 * case, whether or not the test for interruption occurs before the lock
380 * <p>The return value indicates whether the deadline has elapsed,
381 * which can be used as follows:
383 * synchronized boolean aMethod(Date deadline) {
384 * boolean stillWaiting = true;
385 * while (!conditionBeingWaitedFor) {
387 * stillWaiting = theCondition.awaitUntil(deadline);
395 * <p><b>Implementation Considerations</b>
397 * <p>The current thread is assumed to hold the lock associated with this
398 * {@code Condition} when this method is called.
399 * It is up to the implementation to determine if this is
400 * the case and if not, how to respond. Typically, an exception will be
401 * thrown (such as {@link IllegalMonitorStateException}) and the
402 * implementation must document that fact.
404 * <p>An implementation can favor responding to an interrupt over normal
405 * method return in response to a signal, or over indicating the passing
406 * of the specified deadline. In either case the implementation
407 * must ensure that the signal is redirected to another waiting thread, if
410 * @param deadline the absolute time to wait until
411 * @return {@code false} if the deadline has elapsed upon return, else
413 * @throws InterruptedException if the current thread is interrupted
414 * (and interruption of thread suspension is supported)
416 boolean awaitUntil(Date deadline) throws InterruptedException;
419 * Wakes up one waiting thread.
421 * <p>If any threads are waiting on this condition then one
422 * is selected for waking up. That thread must then re-acquire the
423 * lock before returning from {@code await}.
428 * Wakes up all waiting threads.
430 * <p>If any threads are waiting on this condition then they are
431 * all woken up. Each thread must re-acquire the lock before it can
432 * return from {@code await}.