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 7package java.util.concurrent.locks; 8import java.util.concurrent.*; 9import java.util.Date; 10 11/** 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 19 * monitor methods. 20 * 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}. 30 * 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. 34 * 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. 45 * <pre> 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> 50 * 51 * final Object[] items = new Object[100]; 52 * int putptr, takeptr, count; 53 * 54 * public void put(Object x) throws InterruptedException { 55 * <b>lock.lock(); 56 * try {</b> 57 * while (count == items.length) 58 * <b>notFull.await();</b> 59 * items[putptr] = x; 60 * if (++putptr == items.length) putptr = 0; 61 * ++count; 62 * <b>notEmpty.signal();</b> 63 * <b>} finally { 64 * lock.unlock(); 65 * }</b> 66 * } 67 * 68 * public Object take() throws InterruptedException { 69 * <b>lock.lock(); 70 * try {</b> 71 * while (count == 0) 72 * <b>notEmpty.await();</b> 73 * Object x = items[takeptr]; 74 * if (++takeptr == items.length) takeptr = 0; 75 * --count; 76 * <b>notFull.signal();</b> 77 * return x; 78 * <b>} finally { 79 * lock.unlock(); 80 * }</b> 81 * } 82 * } 83 * </pre> 84 * 85 * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides 86 * this functionality, so there is no reason to implement this 87 * sample usage class.) 88 * 89 * <p>A {@code Condition} implementation can provide behavior and semantics 90 * that is 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. 96 * 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. 107 * 108 * <p>Except where noted, passing a {@code null} value for any parameter 109 * will result in a {@link NullPointerException} being thrown. 110 * 111 * <h3>Implementation Considerations</h3> 112 * 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. 122 * 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. 130 * 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 * 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 139 * in this interface. 140 * 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 that may have 145 * unblocked the thread. An implementation should document this behavior. 146 * 147 * @since 1.5 148 * @author Doug Lea 149 */ 150public interface Condition { 151 152 /** 153 * Causes the current thread to wait until it is signalled or 154 * {@linkplain Thread#interrupt interrupted}. 155 * 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: 159 * <ul> 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. 168 * </ul> 169 * 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. 173 * 174 * <p>If the current thread: 175 * <ul> 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, 179 * </ul> 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 183 * is released. 184 * 185 * <p><b>Implementation Considerations</b> 186 * 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. 193 * 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 197 * there is one. 198 * 199 * @throws InterruptedException if the current thread is interrupted 200 * (and interruption of thread suspension is supported) 201 */ 202 void await() throws InterruptedException; 203 204 /** 205 * Causes the current thread to wait until it is signalled. 206 * 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: 210 * <ul> 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. 217 * </ul> 218 * 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. 222 * 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 227 * be set. 228 * 229 * <p><b>Implementation Considerations</b> 230 * 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. 237 */ 238 void awaitUninterruptibly(); 239 240 /** 241 * Causes the current thread to wait until it is signalled or interrupted, 242 * or the specified waiting time elapses. 243 * 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: 247 * <ul> 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. 257 * </ul> 258 * 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. 262 * 263 * <p>If the current thread: 264 * <ul> 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, 268 * </ul> 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 272 * is released. 273 * 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: 281 * 282 * <pre> {@code 283 * boolean aMethod(long timeout, TimeUnit unit) { 284 * long nanos = unit.toNanos(timeout); 285 * lock.lock(); 286 * try { 287 * while (!conditionBeingWaitedFor()) { 288 * if (nanos <= 0L) 289 * return false; 290 * nanos = theCondition.awaitNanos(nanos); 291 * } 292 * // ... 293 * } finally { 294 * lock.unlock(); 295 * } 296 * }}</pre> 297 * 298 * <p> Design note: This method requires a nanosecond argument so 299 * as to avoid truncation errors in reporting remaining times. 300 * Such precision loss would make it difficult for programmers to 301 * ensure that total waiting times are not systematically shorter 302 * than specified when re-waits occur. 303 * 304 * <p><b>Implementation Considerations</b> 305 * 306 * <p>The current thread is assumed to hold the lock associated with this 307 * {@code Condition} when this method is called. 308 * It is up to the implementation to determine if this is 309 * the case and if not, how to respond. Typically, an exception will be 310 * thrown (such as {@link IllegalMonitorStateException}) and the 311 * implementation must document that fact. 312 * 313 * <p>An implementation can favor responding to an interrupt over normal 314 * method return in response to a signal, or over indicating the elapse 315 * of the specified waiting time. In either case the implementation 316 * must ensure that the signal is redirected to another waiting thread, if 317 * there is one. 318 * 319 * @param nanosTimeout the maximum time to wait, in nanoseconds 320 * @return an estimate of the {@code nanosTimeout} value minus 321 * the time spent waiting upon return from this method. 322 * A positive value may be used as the argument to a 323 * subsequent call to this method to finish waiting out 324 * the desired time. A value less than or equal to zero 325 * indicates that no time remains. 326 * @throws InterruptedException if the current thread is interrupted 327 * (and interruption of thread suspension is supported) 328 */ 329 long awaitNanos(long nanosTimeout) throws InterruptedException; 330 331 /** 332 * Causes the current thread to wait until it is signalled or interrupted, 333 * or the specified waiting time elapses. This method is behaviorally 334 * equivalent to: 335 * <pre> {@code awaitNanos(unit.toNanos(time)) > 0}</pre> 336 * 337 * @param time the maximum time to wait 338 * @param unit the time unit of the {@code time} argument 339 * @return {@code false} if the waiting time detectably elapsed 340 * before return from the method, else {@code true} 341 * @throws InterruptedException if the current thread is interrupted 342 * (and interruption of thread suspension is supported) 343 */ 344 boolean await(long time, TimeUnit unit) throws InterruptedException; 345 346 /** 347 * Causes the current thread to wait until it is signalled or interrupted, 348 * or the specified deadline elapses. 349 * 350 * <p>The lock associated with this condition is atomically 351 * released and the current thread becomes disabled for thread scheduling 352 * purposes and lies dormant until <em>one</em> of five things happens: 353 * <ul> 354 * <li>Some other thread invokes the {@link #signal} method for this 355 * {@code Condition} and the current thread happens to be chosen as the 356 * thread to be awakened; or 357 * <li>Some other thread invokes the {@link #signalAll} method for this 358 * {@code Condition}; or 359 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the 360 * current thread, and interruption of thread suspension is supported; or 361 * <li>The specified deadline elapses; or 362 * <li>A "<em>spurious wakeup</em>" occurs. 363 * </ul> 364 * 365 * <p>In all cases, before this method can return the current thread must 366 * re-acquire the lock associated with this condition. When the 367 * thread returns it is <em>guaranteed</em> to hold this lock. 368 * 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 * 382 * <p>The return value indicates whether the deadline has elapsed, 383 * which can be used as follows: 384 * <pre> {@code 385 * boolean aMethod(Date deadline) { 386 * boolean stillWaiting = true; 387 * lock.lock(); 388 * try { 389 * while (!conditionBeingWaitedFor()) { 390 * if (!stillWaiting) 391 * return false; 392 * stillWaiting = theCondition.awaitUntil(deadline); 393 * } 394 * // ... 395 * } finally { 396 * lock.unlock(); 397 * } 398 * }}</pre> 399 * 400 * <p><b>Implementation Considerations</b> 401 * 402 * <p>The current thread is assumed to hold the lock associated with this 403 * {@code Condition} when this method is called. 404 * It is up to the implementation to determine if this is 405 * the case and if not, how to respond. Typically, an exception will be 406 * thrown (such as {@link IllegalMonitorStateException}) and the 407 * implementation must document that fact. 408 * 409 * <p>An implementation can favor responding to an interrupt over normal 410 * method return in response to a signal, or over indicating the passing 411 * of the specified deadline. In either case the implementation 412 * must ensure that the signal is redirected to another waiting thread, if 413 * there is one. 414 * 415 * @param deadline the absolute time to wait until 416 * @return {@code false} if the deadline has elapsed upon return, else 417 * {@code true} 418 * @throws InterruptedException if the current thread is interrupted 419 * (and interruption of thread suspension is supported) 420 */ 421 boolean awaitUntil(Date deadline) throws InterruptedException; 422 423 /** 424 * Wakes up one waiting thread. 425 * 426 * <p>If any threads are waiting on this condition then one 427 * is selected for waking up. That thread must then re-acquire the 428 * lock before returning from {@code await}. 429 * 430 * <p><b>Implementation Considerations</b> 431 * 432 * <p>An implementation may (and typically does) require that the 433 * current thread hold the lock associated with this {@code 434 * Condition} when this method is called. Implementations must 435 * document this precondition and any actions taken if the lock is 436 * not held. Typically, an exception such as {@link 437 * IllegalMonitorStateException} will be thrown. 438 */ 439 void signal(); 440 441 /** 442 * Wakes up all waiting threads. 443 * 444 * <p>If any threads are waiting on this condition then they are 445 * all woken up. Each thread must re-acquire the lock before it can 446 * return from {@code await}. 447 * 448 * <p><b>Implementation Considerations</b> 449 * 450 * <p>An implementation may (and typically does) require that the 451 * current thread hold the lock associated with this {@code 452 * Condition} when this method is called. Implementations must 453 * document this precondition and any actions taken if the lock is 454 * not held. Typically, an exception such as {@link 455 * IllegalMonitorStateException} will be thrown. 456 */ 457 void signalAll(); 458} 459