src/share/classes/java/util/concurrent/locks/Condition.java

Print this page




 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 &gt; 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 }