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

Print this page

        

@@ -306,22 +306,25 @@
      * timed out. This value can be used to determine whether and how
      * long to re-wait in cases where the wait returns but an awaited
      * condition still does not hold. Typical uses of this method take
      * the following form:
      *
-     * <pre>
-     * synchronized boolean aMethod(long timeout, TimeUnit unit) {
-     *   long nanosTimeout = unit.toNanos(timeout);
-     *   while (!conditionBeingWaitedFor) {
-     *     if (nanosTimeout &gt; 0)
-     *         nanosTimeout = theCondition.awaitNanos(nanosTimeout);
-     *      else
+     *  <pre> {@code
+     * boolean aMethod(long timeout, TimeUnit unit) {
+     *   long nanos = unit.toNanos(timeout);
+     *   lock.lock();
+     *   try {
+     *     while (!conditionBeingWaitedFor()) {
+     *       if (nanos <= 0L)
      *        return false;
+     *       nanos = theCondition.awaitNanos(nanos);
      *   }
      *   // ...
+     *   } finally {
+     *     lock.unlock();
      * }
-     * </pre>
+     * }}</pre>
      *
      * <p> Design note: This method requires a nanosecond argument so
      * as to avoid truncation errors in reporting remaining times.
      * Such precision loss would make it difficult for programmers to
      * ensure that total waiting times are not systematically shorter

@@ -406,22 +409,25 @@
      * is released.
      *
      *
      * <p>The return value indicates whether the deadline has elapsed,
      * which can be used as follows:
-     * <pre>
-     * synchronized boolean aMethod(Date deadline) {
+     *  <pre> {@code
+     * boolean aMethod(Date deadline) {
      *   boolean stillWaiting = true;
-     *   while (!conditionBeingWaitedFor) {
-     *     if (stillWaiting)
-     *         stillWaiting = theCondition.awaitUntil(deadline);
-     *      else
+     *   lock.lock();
+     *   try {
+     *     while (!conditionBeingWaitedFor()) {
+     *       if (!stillWaiting)
      *        return false;
+     *       stillWaiting = theCondition.awaitUntil(deadline);
      *   }
      *   // ...
+     *   } finally {
+     *     lock.unlock();
      * }
-     * </pre>
+     * }}</pre>
      *
      * <p><b>Implementation Considerations</b>
      *
      * <p>The current thread is assumed to hold the lock associated with this
      * {@code Condition} when this method is called.

@@ -448,17 +454,35 @@
      * Wakes up one waiting thread.
      *
      * <p>If any threads are waiting on this condition then one
      * is selected for waking up. That thread must then re-acquire the
      * lock before returning from {@code await}.
+     *
+     * <p><b>Implementation Considerations</b>
+     *
+     * <p>The current thread is assumed to hold the lock associated
+     * with this {@code Condition} when this method is called.  It is
+     * up to the implementation to determine if this is the case and
+     * if not, how to respond. Typically, an exception will be thrown
+     * (such as {@link IllegalMonitorStateException}) and the
+     * implementation must document that fact.
      */
     void signal();
 
     /**
      * Wakes up all waiting threads.
      *
      * <p>If any threads are waiting on this condition then they are
      * all woken up. Each thread must re-acquire the lock before it can
      * return from {@code await}.
+     *
+     * <p><b>Implementation Considerations</b>
+     *
+     * <p>The current thread is assumed to hold the lock associated
+     * with this {@code Condition} when this method is called.  It is
+     * up to the implementation to determine if this is the case and
+     * if not, how to respond. Typically, an exception will be thrown
+     * (such as {@link IllegalMonitorStateException}) and the
+     * implementation must document that fact.
      */
     void signalAll();
 }