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 > 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();
}