001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent.locks;
037
038 import java.util.concurrent.*;
039 import java.util.Date;
040
041 /**
042 * {@code Condition} factors out the {@code Object} monitor
043 * methods ({@link Object#wait() wait}, {@link Object#notify notify}
044 * and {@link Object#notifyAll notifyAll}) into distinct objects to
045 * give the effect of having multiple wait-sets per object, by
046 * combining them with the use of arbitrary {@link Lock} implementations.
047 * Where a {@code Lock} replaces the use of {@code synchronized} methods
048 * and statements, a {@code Condition} replaces the use of the Object
049 * monitor methods.
050 *
051 * <p>Conditions (also known as <em>condition queues</em> or
052 * <em>condition variables</em>) provide a means for one thread to
053 * suspend execution (to "wait") until notified by another
054 * thread that some state condition may now be true. Because access
055 * to this shared state information occurs in different threads, it
056 * must be protected, so a lock of some form is associated with the
057 * condition. The key property that waiting for a condition provides
058 * is that it <em>atomically</em> releases the associated lock and
059 * suspends the current thread, just like {@code Object.wait}.
060 *
061 * <p>A {@code Condition} instance is intrinsically bound to a lock.
062 * To obtain a {@code Condition} instance for a particular {@link Lock}
063 * instance use its {@link Lock#newCondition newCondition()} method.
064 *
065 * <p>As an example, suppose we have a bounded buffer which supports
066 * {@code put} and {@code take} methods. If a
067 * {@code take} is attempted on an empty buffer, then the thread will block
068 * until an item becomes available; if a {@code put} is attempted on a
069 * full buffer, then the thread will block until a space becomes available.
070 * We would like to keep waiting {@code put} threads and {@code take}
071 * threads in separate wait-sets so that we can use the optimization of
072 * only notifying a single thread at a time when items or spaces become
073 * available in the buffer. This can be achieved using two
074 * {@link Condition} instances.
075 * <pre>
076 * class BoundedBuffer {
077 * <b>final Lock lock = new ReentrantLock();</b>
078 * final Condition notFull = <b>lock.newCondition(); </b>
079 * final Condition notEmpty = <b>lock.newCondition(); </b>
080 *
081 * final Object[] items = new Object[100];
082 * int putptr, takeptr, count;
083 *
084 * public void put(Object x) throws InterruptedException {
085 * <b>lock.lock();
086 * try {</b>
087 * while (count == items.length)
088 * <b>notFull.await();</b>
089 * items[putptr] = x;
090 * if (++putptr == items.length) putptr = 0;
091 * ++count;
092 * <b>notEmpty.signal();</b>
093 * <b>} finally {
094 * lock.unlock();
095 * }</b>
096 * }
097 *
098 * public Object take() throws InterruptedException {
099 * <b>lock.lock();
100 * try {</b>
101 * while (count == 0)
102 * <b>notEmpty.await();</b>
103 * Object x = items[takeptr];
104 * if (++takeptr == items.length) takeptr = 0;
105 * --count;
106 * <b>notFull.signal();</b>
107 * return x;
108 * <b>} finally {
109 * lock.unlock();
110 * }</b>
111 * }
112 * }
113 * </pre>
114 *
115 * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
116 * this functionality, so there is no reason to implement this
117 * sample usage class.)
118 *
119 * <p>A {@code Condition} implementation can provide behavior and semantics
120 * that is
121 * different from that of the {@code Object} monitor methods, such as
122 * guaranteed ordering for notifications, or not requiring a lock to be held
123 * when performing notifications.
124 * If an implementation provides such specialized semantics then the
125 * implementation must document those semantics.
126 *
127 * <p>Note that {@code Condition} instances are just normal objects and can
128 * themselves be used as the target in a {@code synchronized} statement,
129 * and can have their own monitor {@link Object#wait wait} and
130 * {@link Object#notify notification} methods invoked.
131 * Acquiring the monitor lock of a {@code Condition} instance, or using its
132 * monitor methods, has no specified relationship with acquiring the
133 * {@link Lock} associated with that {@code Condition} or the use of its
134 * {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
135 * It is recommended that to avoid confusion you never use {@code Condition}
136 * instances in this way, except perhaps within their own implementation.
137 *
138 * <p>Except where noted, passing a {@code null} value for any parameter
139 * will result in a {@link NullPointerException} being thrown.
140 *
141 * <h3>Implementation Considerations</h3>
142 *
143 * <p>When waiting upon a {@code Condition}, a "<em>spurious
144 * wakeup</em>" is permitted to occur, in
145 * general, as a concession to the underlying platform semantics.
146 * This has little practical impact on most application programs as a
147 * {@code Condition} should always be waited upon in a loop, testing
148 * the state predicate that is being waited for. An implementation is
149 * free to remove the possibility of spurious wakeups but it is
150 * recommended that applications programmers always assume that they can
151 * occur and so always wait in a loop.
152 *
153 * <p>The three forms of condition waiting
154 * (interruptible, non-interruptible, and timed) may differ in their ease of
155 * implementation on some platforms and in their performance characteristics.
156 * In particular, it may be difficult to provide these features and maintain
157 * specific semantics such as ordering guarantees.
158 * Further, the ability to interrupt the actual suspension of the thread may
159 * not always be feasible to implement on all platforms.
160 *
161 * <p>Consequently, an implementation is not required to define exactly the
162 * same guarantees or semantics for all three forms of waiting, nor is it
163 * required to support interruption of the actual suspension of the thread.
164 *
165 * <p>An implementation is required to
166 * clearly document the semantics and guarantees provided by each of the
167 * waiting methods, and when an implementation does support interruption of
168 * thread suspension then it must obey the interruption semantics as defined
169 * in this interface.
170 *
171 * <p>As interruption generally implies cancellation, and checks for
172 * interruption are often infrequent, an implementation can favor responding
173 * to an interrupt over normal method return. This is true even if it can be
174 * shown that the interrupt occurred after another action may have unblocked
175 * the thread. An implementation should document this behavior.
176 *
177 * @since 1.5
178 * @author Doug Lea
179 */
180 public interface Condition {
181
182 /**
183 * Causes the current thread to wait until it is signalled or
184 * {@linkplain Thread#interrupt interrupted}.
185 *
186 * <p>The lock associated with this {@code Condition} is atomically
187 * released and the current thread becomes disabled for thread scheduling
188 * purposes and lies dormant until <em>one</em> of four things happens:
189 * <ul>
190 * <li>Some other thread invokes the {@link #signal} method for this
191 * {@code Condition} and the current thread happens to be chosen as the
192 * thread to be awakened; or
193 * <li>Some other thread invokes the {@link #signalAll} method for this
194 * {@code Condition}; or
195 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
196 * current thread, and interruption of thread suspension is supported; or
197 * <li>A "<em>spurious wakeup</em>" occurs.
198 * </ul>
199 *
200 * <p>In all cases, before this method can return the current thread must
201 * re-acquire the lock associated with this condition. When the
202 * thread returns it is <em>guaranteed</em> to hold this lock.
203 *
204 * <p>If the current thread:
205 * <ul>
206 * <li>has its interrupted status set on entry to this method; or
207 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
208 * and interruption of thread suspension is supported,
209 * </ul>
210 * then {@link InterruptedException} is thrown and the current thread's
211 * interrupted status is cleared. It is not specified, in the first
212 * case, whether or not the test for interruption occurs before the lock
213 * is released.
214 *
215 * <p><b>Implementation Considerations</b>
216 *
217 * <p>The current thread is assumed to hold the lock associated with this
218 * {@code Condition} when this method is called.
219 * It is up to the implementation to determine if this is
220 * the case and if not, how to respond. Typically, an exception will be
221 * thrown (such as {@link IllegalMonitorStateException}) and the
222 * implementation must document that fact.
223 *
224 * <p>An implementation can favor responding to an interrupt over normal
225 * method return in response to a signal. In that case the implementation
226 * must ensure that the signal is redirected to another waiting thread, if
227 * there is one.
228 *
229 * @throws InterruptedException if the current thread is interrupted
230 * (and interruption of thread suspension is supported)
231 */
232 void await() throws InterruptedException;
233
234 /**
235 * Causes the current thread to wait until it is signalled.
236 *
237 * <p>The lock associated with this condition is atomically
238 * released and the current thread becomes disabled for thread scheduling
239 * purposes and lies dormant until <em>one</em> of three things happens:
240 * <ul>
241 * <li>Some other thread invokes the {@link #signal} method for this
242 * {@code Condition} and the current thread happens to be chosen as the
243 * thread to be awakened; or
244 * <li>Some other thread invokes the {@link #signalAll} method for this
245 * {@code Condition}; or
246 * <li>A "<em>spurious wakeup</em>" occurs.
247 * </ul>
248 *
249 * <p>In all cases, before this method can return the current thread must
250 * re-acquire the lock associated with this condition. When the
251 * thread returns it is <em>guaranteed</em> to hold this lock.
252 *
253 * <p>If the current thread's interrupted status is set when it enters
254 * this method, or it is {@linkplain Thread#interrupt interrupted}
255 * while waiting, it will continue to wait until signalled. When it finally
256 * returns from this method its interrupted status will still
257 * be set.
258 *
259 * <p><b>Implementation Considerations</b>
260 *
261 * <p>The current thread is assumed to hold the lock associated with this
262 * {@code Condition} when this method is called.
263 * It is up to the implementation to determine if this is
264 * the case and if not, how to respond. Typically, an exception will be
265 * thrown (such as {@link IllegalMonitorStateException}) and the
266 * implementation must document that fact.
267 */
268 void awaitUninterruptibly();
269
270 /**
271 * Causes the current thread to wait until it is signalled or interrupted,
272 * or the specified waiting time elapses.
273 *
274 * <p>The lock associated with this condition is atomically
275 * released and the current thread becomes disabled for thread scheduling
276 * purposes and lies dormant until <em>one</em> of five things happens:
277 * <ul>
278 * <li>Some other thread invokes the {@link #signal} method for this
279 * {@code Condition} and the current thread happens to be chosen as the
280 * thread to be awakened; or
281 * <li>Some other thread invokes the {@link #signalAll} method for this
282 * {@code Condition}; or
283 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
284 * current thread, and interruption of thread suspension is supported; or
285 * <li>The specified waiting time elapses; or
286 * <li>A "<em>spurious wakeup</em>" occurs.
287 * </ul>
288 *
289 * <p>In all cases, before this method can return the current thread must
290 * re-acquire the lock associated with this condition. When the
291 * thread returns it is <em>guaranteed</em> to hold this lock.
292 *
293 * <p>If the current thread:
294 * <ul>
295 * <li>has its interrupted status set on entry to this method; or
296 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
297 * and interruption of thread suspension is supported,
298 * </ul>
299 * then {@link InterruptedException} is thrown and the current thread's
300 * interrupted status is cleared. It is not specified, in the first
301 * case, whether or not the test for interruption occurs before the lock
302 * is released.
303 *
304 * <p>The method returns an estimate of the number of nanoseconds
305 * remaining to wait given the supplied {@code nanosTimeout}
306 * value upon return, or a value less than or equal to zero if it
307 * timed out. This value can be used to determine whether and how
308 * long to re-wait in cases where the wait returns but an awaited
309 * condition still does not hold. Typical uses of this method take
310 * the following form:
311 *
312 * <pre>
313 * synchronized boolean aMethod(long timeout, TimeUnit unit) {
314 * long nanosTimeout = unit.toNanos(timeout);
315 * while (!conditionBeingWaitedFor) {
316 * if (nanosTimeout > 0)
317 * nanosTimeout = theCondition.awaitNanos(nanosTimeout);
318 * else
319 * return false;
320 * }
321 * // ...
322 * }
323 * </pre>
324 *
325 * <p> Design note: This method requires a nanosecond argument so
326 * as to avoid truncation errors in reporting remaining times.
327 * Such precision loss would make it difficult for programmers to
328 * ensure that total waiting times are not systematically shorter
329 * than specified when re-waits occur.
330 *
331 * <p><b>Implementation Considerations</b>
332 *
333 * <p>The current thread is assumed to hold the lock associated with this
334 * {@code Condition} when this method is called.
335 * It is up to the implementation to determine if this is
336 * the case and if not, how to respond. Typically, an exception will be
337 * thrown (such as {@link IllegalMonitorStateException}) and the
338 * implementation must document that fact.
339 *
340 * <p>An implementation can favor responding to an interrupt over normal
341 * method return in response to a signal, or over indicating the elapse
342 * of the specified waiting time. In either case the implementation
343 * must ensure that the signal is redirected to another waiting thread, if
344 * there is one.
345 *
346 * @param nanosTimeout the maximum time to wait, in nanoseconds
347 * @return an estimate of the {@code nanosTimeout} value minus
348 * the time spent waiting upon return from this method.
349 * A positive value may be used as the argument to a
350 * subsequent call to this method to finish waiting out
351 * the desired time. A value less than or equal to zero
352 * indicates that no time remains.
353 * @throws InterruptedException if the current thread is interrupted
354 * (and interruption of thread suspension is supported)
355 */
356 long awaitNanos(long nanosTimeout) throws InterruptedException;
357
358 /**
359 * Causes the current thread to wait until it is signalled or interrupted,
360 * or the specified waiting time elapses. This method is behaviorally
361 * equivalent to:<br>
362 * <pre>
363 * awaitNanos(unit.toNanos(time)) > 0
364 * </pre>
365 * @param time the maximum time to wait
366 * @param unit the time unit of the {@code time} argument
367 * @return {@code false} if the waiting time detectably elapsed
368 * before return from the method, else {@code true}
369 * @throws InterruptedException if the current thread is interrupted
370 * (and interruption of thread suspension is supported)
371 */
372 boolean await(long time, TimeUnit unit) throws InterruptedException;
373
374 /**
375 * Causes the current thread to wait until it is signalled or interrupted,
376 * or the specified deadline elapses.
377 *
378 * <p>The lock associated with this condition is atomically
379 * released and the current thread becomes disabled for thread scheduling
380 * purposes and lies dormant until <em>one</em> of five things happens:
381 * <ul>
382 * <li>Some other thread invokes the {@link #signal} method for this
383 * {@code Condition} and the current thread happens to be chosen as the
384 * thread to be awakened; or
385 * <li>Some other thread invokes the {@link #signalAll} method for this
386 * {@code Condition}; or
387 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
388 * current thread, and interruption of thread suspension is supported; or
389 * <li>The specified deadline elapses; or
390 * <li>A "<em>spurious wakeup</em>" occurs.
391 * </ul>
392 *
393 * <p>In all cases, before this method can return the current thread must
394 * re-acquire the lock associated with this condition. When the
395 * thread returns it is <em>guaranteed</em> to hold this lock.
396 *
397 *
398 * <p>If the current thread:
399 * <ul>
400 * <li>has its interrupted status set on entry to this method; or
401 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
402 * and interruption of thread suspension is supported,
403 * </ul>
404 * then {@link InterruptedException} is thrown and the current thread's
405 * interrupted status is cleared. It is not specified, in the first
406 * case, whether or not the test for interruption occurs before the lock
407 * is released.
408 *
409 *
410 * <p>The return value indicates whether the deadline has elapsed,
411 * which can be used as follows:
412 * <pre>
413 * synchronized boolean aMethod(Date deadline) {
414 * boolean stillWaiting = true;
415 * while (!conditionBeingWaitedFor) {
416 * if (stillWaiting)
417 * stillWaiting = theCondition.awaitUntil(deadline);
418 * else
419 * return false;
420 * }
421 * // ...
422 * }
423 * </pre>
424 *
425 * <p><b>Implementation Considerations</b>
426 *
427 * <p>The current thread is assumed to hold the lock associated with this
428 * {@code Condition} when this method is called.
429 * It is up to the implementation to determine if this is
430 * the case and if not, how to respond. Typically, an exception will be
431 * thrown (such as {@link IllegalMonitorStateException}) and the
432 * implementation must document that fact.
433 *
434 * <p>An implementation can favor responding to an interrupt over normal
435 * method return in response to a signal, or over indicating the passing
436 * of the specified deadline. In either case the implementation
437 * must ensure that the signal is redirected to another waiting thread, if
438 * there is one.
439 *
440 * @param deadline the absolute time to wait until
441 * @return {@code false} if the deadline has elapsed upon return, else
442 * {@code true}
443 * @throws InterruptedException if the current thread is interrupted
444 * (and interruption of thread suspension is supported)
445 */
446 boolean awaitUntil(Date deadline) throws InterruptedException;
447
448 /**
449 * Wakes up one waiting thread.
450 *
451 * <p>If any threads are waiting on this condition then one
452 * is selected for waking up. That thread must then re-acquire the
453 * lock before returning from {@code await}.
454 */
455 void signal();
456
457 /**
458 * Wakes up all waiting threads.
459 *
460 * <p>If any threads are waiting on this condition then they are
461 * all woken up. Each thread must re-acquire the lock before it can
462 * return from {@code await}.
463 */
464 void signalAll();
465 }
|