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