Print this page


Split Close
Expand all
Collapse all
          --- old/src/share/classes/java/util/concurrent/locks/Condition.java
          +++ new/src/share/classes/java/util/concurrent/locks/Condition.java
↓ open down ↓ 300 lines elided ↑ open up ↑
 301  301       * is released.
 302  302       *
 303  303       * <p>The method returns an estimate of the number of nanoseconds
 304  304       * remaining to wait given the supplied {@code nanosTimeout}
 305  305       * value upon return, or a value less than or equal to zero if it
 306  306       * timed out. This value can be used to determine whether and how
 307  307       * long to re-wait in cases where the wait returns but an awaited
 308  308       * condition still does not hold. Typical uses of this method take
 309  309       * the following form:
 310  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;
      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();
 319  324       *   }
 320      -     *   // ...
 321      -     * }
 322      -     * </pre>
      325 +     * }}</pre>
 323  326       *
 324  327       * <p> Design note: This method requires a nanosecond argument so
 325  328       * as to avoid truncation errors in reporting remaining times.
 326  329       * Such precision loss would make it difficult for programmers to
 327  330       * ensure that total waiting times are not systematically shorter
 328  331       * than specified when re-waits occur.
 329  332       *
 330  333       * <p><b>Implementation Considerations</b>
 331  334       *
 332  335       * <p>The current thread is assumed to hold the lock associated with this
↓ open down ↓ 68 lines elided ↑ open up ↑
 401  404       * and interruption of thread suspension is supported,
 402  405       * </ul>
 403  406       * then {@link InterruptedException} is thrown and the current thread's
 404  407       * interrupted status is cleared. It is not specified, in the first
 405  408       * case, whether or not the test for interruption occurs before the lock
 406  409       * is released.
 407  410       *
 408  411       *
 409  412       * <p>The return value indicates whether the deadline has elapsed,
 410  413       * which can be used as follows:
 411      -     * <pre>
 412      -     * synchronized boolean aMethod(Date deadline) {
      414 +     *  <pre> {@code
      415 +     * boolean aMethod(Date deadline) {
 413  416       *   boolean stillWaiting = true;
 414      -     *   while (!conditionBeingWaitedFor) {
 415      -     *     if (stillWaiting)
 416      -     *         stillWaiting = theCondition.awaitUntil(deadline);
 417      -     *      else
 418      -     *        return false;
      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();
 419  427       *   }
 420      -     *   // ...
 421      -     * }
 422      -     * </pre>
      428 +     * }}</pre>
 423  429       *
 424  430       * <p><b>Implementation Considerations</b>
 425  431       *
 426  432       * <p>The current thread is assumed to hold the lock associated with this
 427  433       * {@code Condition} when this method is called.
 428  434       * It is up to the implementation to determine if this is
 429  435       * the case and if not, how to respond. Typically, an exception will be
 430  436       * thrown (such as {@link IllegalMonitorStateException}) and the
 431  437       * implementation must document that fact.
 432  438       *
↓ open down ↓ 10 lines elided ↑ open up ↑
 443  449       *         (and interruption of thread suspension is supported)
 444  450       */
 445  451      boolean awaitUntil(Date deadline) throws InterruptedException;
 446  452  
 447  453      /**
 448  454       * Wakes up one waiting thread.
 449  455       *
 450  456       * <p>If any threads are waiting on this condition then one
 451  457       * is selected for waking up. That thread must then re-acquire the
 452  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.
 453  468       */
 454  469      void signal();
 455  470  
 456  471      /**
 457  472       * Wakes up all waiting threads.
 458  473       *
 459  474       * <p>If any threads are waiting on this condition then they are
 460  475       * all woken up. Each thread must re-acquire the lock before it can
 461  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.
 462  486       */
 463  487      void signalAll();
 464  488  }
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX