291 * 292 * <p>If the current thread: 293 * <ul> 294 * <li>has its interrupted status set on entry to this method; or 295 * <li>is {@linkplain Thread#interrupt interrupted} while waiting 296 * and interruption of thread suspension is supported, 297 * </ul> 298 * then {@link InterruptedException} is thrown and the current thread's 299 * interrupted status is cleared. It is not specified, in the first 300 * case, whether or not the test for interruption occurs before the lock 301 * is released. 302 * 303 * <p>The method returns an estimate of the number of nanoseconds 304 * remaining to wait given the supplied {@code nanosTimeout} 305 * value upon return, or a value less than or equal to zero if it 306 * timed out. This value can be used to determine whether and how 307 * long to re-wait in cases where the wait returns but an awaited 308 * condition still does not hold. Typical uses of this method take 309 * the following form: 310 * 311 * <pre> 312 * synchronized boolean aMethod(long timeout, TimeUnit unit) { 313 * long nanosTimeout = unit.toNanos(timeout); 314 * while (!conditionBeingWaitedFor) { 315 * if (nanosTimeout > 0) 316 * nanosTimeout = theCondition.awaitNanos(nanosTimeout); 317 * else 318 * return false; 319 * } 320 * // ... 321 * } 322 * </pre> 323 * 324 * <p> Design note: This method requires a nanosecond argument so 325 * as to avoid truncation errors in reporting remaining times. 326 * Such precision loss would make it difficult for programmers to 327 * ensure that total waiting times are not systematically shorter 328 * than specified when re-waits occur. 329 * 330 * <p><b>Implementation Considerations</b> 331 * 332 * <p>The current thread is assumed to hold the lock associated with this 333 * {@code Condition} when this method is called. 334 * It is up to the implementation to determine if this is 335 * the case and if not, how to respond. Typically, an exception will be 336 * thrown (such as {@link IllegalMonitorStateException}) and the 337 * implementation must document that fact. 338 * 339 * <p>An implementation can favor responding to an interrupt over normal 340 * method return in response to a signal, or over indicating the elapse 341 * of the specified waiting time. In either case the implementation 342 * must ensure that the signal is redirected to another waiting thread, if 391 * 392 * <p>In all cases, before this method can return the current thread must 393 * re-acquire the lock associated with this condition. When the 394 * thread returns it is <em>guaranteed</em> to hold this lock. 395 * 396 * 397 * <p>If the current thread: 398 * <ul> 399 * <li>has its interrupted status set on entry to this method; or 400 * <li>is {@linkplain Thread#interrupt interrupted} while waiting 401 * and interruption of thread suspension is supported, 402 * </ul> 403 * then {@link InterruptedException} is thrown and the current thread's 404 * interrupted status is cleared. It is not specified, in the first 405 * case, whether or not the test for interruption occurs before the lock 406 * is released. 407 * 408 * 409 * <p>The return value indicates whether the deadline has elapsed, 410 * which can be used as follows: 411 * <pre> 412 * synchronized boolean aMethod(Date deadline) { 413 * boolean stillWaiting = true; 414 * while (!conditionBeingWaitedFor) { 415 * if (stillWaiting) 416 * stillWaiting = theCondition.awaitUntil(deadline); 417 * else 418 * return false; 419 * } 420 * // ... 421 * } 422 * </pre> 423 * 424 * <p><b>Implementation Considerations</b> 425 * 426 * <p>The current thread is assumed to hold the lock associated with this 427 * {@code Condition} when this method is called. 428 * It is up to the implementation to determine if this is 429 * the case and if not, how to respond. Typically, an exception will be 430 * thrown (such as {@link IllegalMonitorStateException}) and the 431 * implementation must document that fact. 432 * 433 * <p>An implementation can favor responding to an interrupt over normal 434 * method return in response to a signal, or over indicating the passing 435 * of the specified deadline. In either case the implementation 436 * must ensure that the signal is redirected to another waiting thread, if 437 * there is one. 438 * 439 * @param deadline the absolute time to wait until 440 * @return {@code false} if the deadline has elapsed upon return, else 441 * {@code true} 442 * @throws InterruptedException if the current thread is interrupted 443 * (and interruption of thread suspension is supported) 444 */ 445 boolean awaitUntil(Date deadline) throws InterruptedException; 446 447 /** 448 * Wakes up one waiting thread. 449 * 450 * <p>If any threads are waiting on this condition then one 451 * is selected for waking up. That thread must then re-acquire the 452 * lock before returning from {@code await}. 453 */ 454 void signal(); 455 456 /** 457 * Wakes up all waiting threads. 458 * 459 * <p>If any threads are waiting on this condition then they are 460 * all woken up. Each thread must re-acquire the lock before it can 461 * return from {@code await}. 462 */ 463 void signalAll(); 464 } | 291 * 292 * <p>If the current thread: 293 * <ul> 294 * <li>has its interrupted status set on entry to this method; or 295 * <li>is {@linkplain Thread#interrupt interrupted} while waiting 296 * and interruption of thread suspension is supported, 297 * </ul> 298 * then {@link InterruptedException} is thrown and the current thread's 299 * interrupted status is cleared. It is not specified, in the first 300 * case, whether or not the test for interruption occurs before the lock 301 * is released. 302 * 303 * <p>The method returns an estimate of the number of nanoseconds 304 * remaining to wait given the supplied {@code nanosTimeout} 305 * value upon return, or a value less than or equal to zero if it 306 * timed out. This value can be used to determine whether and how 307 * long to re-wait in cases where the wait returns but an awaited 308 * condition still does not hold. Typical uses of this method take 309 * the following form: 310 * 311 * <pre> {@code 312 * boolean aMethod(long timeout, TimeUnit unit) { 313 * long nanos = unit.toNanos(timeout); 314 * lock.lock(); 315 * try { 316 * while (!conditionBeingWaitedFor()) { 317 * if (nanos <= 0L) 318 * return false; 319 * nanos = theCondition.awaitNanos(nanos); 320 * } 321 * // ... 322 * } finally { 323 * lock.unlock(); 324 * } 325 * }}</pre> 326 * 327 * <p> Design note: This method requires a nanosecond argument so 328 * as to avoid truncation errors in reporting remaining times. 329 * Such precision loss would make it difficult for programmers to 330 * ensure that total waiting times are not systematically shorter 331 * than specified when re-waits occur. 332 * 333 * <p><b>Implementation Considerations</b> 334 * 335 * <p>The current thread is assumed to hold the lock associated with this 336 * {@code Condition} when this method is called. 337 * It is up to the implementation to determine if this is 338 * the case and if not, how to respond. Typically, an exception will be 339 * thrown (such as {@link IllegalMonitorStateException}) and the 340 * implementation must document that fact. 341 * 342 * <p>An implementation can favor responding to an interrupt over normal 343 * method return in response to a signal, or over indicating the elapse 344 * of the specified waiting time. In either case the implementation 345 * must ensure that the signal is redirected to another waiting thread, if 394 * 395 * <p>In all cases, before this method can return the current thread must 396 * re-acquire the lock associated with this condition. When the 397 * thread returns it is <em>guaranteed</em> to hold this lock. 398 * 399 * 400 * <p>If the current thread: 401 * <ul> 402 * <li>has its interrupted status set on entry to this method; or 403 * <li>is {@linkplain Thread#interrupt interrupted} while waiting 404 * and interruption of thread suspension is supported, 405 * </ul> 406 * then {@link InterruptedException} is thrown and the current thread's 407 * interrupted status is cleared. It is not specified, in the first 408 * case, whether or not the test for interruption occurs before the lock 409 * is released. 410 * 411 * 412 * <p>The return value indicates whether the deadline has elapsed, 413 * which can be used as follows: 414 * <pre> {@code 415 * boolean aMethod(Date deadline) { 416 * boolean stillWaiting = true; 417 * lock.lock(); 418 * try { 419 * while (!conditionBeingWaitedFor()) { 420 * if (!stillWaiting) 421 * return false; 422 * stillWaiting = theCondition.awaitUntil(deadline); 423 * } 424 * // ... 425 * } finally { 426 * lock.unlock(); 427 * } 428 * }}</pre> 429 * 430 * <p><b>Implementation Considerations</b> 431 * 432 * <p>The current thread is assumed to hold the lock associated with this 433 * {@code Condition} when this method is called. 434 * It is up to the implementation to determine if this is 435 * the case and if not, how to respond. Typically, an exception will be 436 * thrown (such as {@link IllegalMonitorStateException}) and the 437 * implementation must document that fact. 438 * 439 * <p>An implementation can favor responding to an interrupt over normal 440 * method return in response to a signal, or over indicating the passing 441 * of the specified deadline. In either case the implementation 442 * must ensure that the signal is redirected to another waiting thread, if 443 * there is one. 444 * 445 * @param deadline the absolute time to wait until 446 * @return {@code false} if the deadline has elapsed upon return, else 447 * {@code true} 448 * @throws InterruptedException if the current thread is interrupted 449 * (and interruption of thread suspension is supported) 450 */ 451 boolean awaitUntil(Date deadline) throws InterruptedException; 452 453 /** 454 * Wakes up one waiting thread. 455 * 456 * <p>If any threads are waiting on this condition then one 457 * is selected for waking up. That thread must then re-acquire the 458 * lock before returning from {@code await}. 459 * 460 * <p><b>Implementation Considerations</b> 461 * 462 * <p>The current thread is assumed to hold the lock associated 463 * with this {@code Condition} when this method is called. It is 464 * up to the implementation to determine if this is the case and 465 * if not, how to respond. Typically, an exception will be thrown 466 * (such as {@link IllegalMonitorStateException}) and the 467 * implementation must document that fact. 468 */ 469 void signal(); 470 471 /** 472 * Wakes up all waiting threads. 473 * 474 * <p>If any threads are waiting on this condition then they are 475 * all woken up. Each thread must re-acquire the lock before it can 476 * return from {@code await}. 477 * 478 * <p><b>Implementation Considerations</b> 479 * 480 * <p>The current thread is assumed to hold the lock associated 481 * with this {@code Condition} when this method is called. It is 482 * up to the implementation to determine if this is the case and 483 * if not, how to respond. Typically, an exception will be thrown 484 * (such as {@link IllegalMonitorStateException}) and the 485 * implementation must document that fact. 486 */ 487 void signalAll(); 488 } |