diff --git a/src/java.base/share/classes/java/util/concurrent/locks/Lock.java b/src/java.base/share/classes/java/util/concurrent/locks/Lock.java index 84100e64a13..bd6ce2eb6f9 100644 --- a/src/java.base/share/classes/java/util/concurrent/locks/Lock.java +++ b/src/java.base/share/classes/java/util/concurrent/locks/Lock.java @@ -80,11 +80,11 @@ import java.util.concurrent.TimeUnit; * *
{@code * Lock l = ...; - * l.lock(); + * l.lock(); // lock() as the last statement before the try block * try { * // access the resource protected by this lock * } finally { - * l.unlock(); + * l.unlock(); // unlock() as the first statement in the finally block * }}* * When locking and unlocking occur in different scopes, care must be diff --git a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantLock.java b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantLock.java index c58925b086e..3378ce3983a 100644 --- a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantLock.java +++ b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantLock.java @@ -71,8 +71,9 @@ import jdk.internal.vm.annotation.ReservedStackAccess; * is available even if other threads are waiting. * *
It is recommended practice to always immediately - * follow a call to {@code lock} with a {@code try} block, most - * typically in a before/after construction such as: + * follow a call to {@code lock} with a {@code try} block, and + * to always immediately call {@code unlock} as the + * first statement in the finally block, as follows: * *
{@code * class X { @@ -80,11 +81,11 @@ import jdk.internal.vm.annotation.ReservedStackAccess; * // ... * * public void m() { - * lock.lock(); // block until condition holds + * lock.lock(); // lock() as the last statement before the try block * try { * // ... method body * } finally { - * lock.unlock(); + * lock.unlock(); // unlock() as the first statement in the finally block * } * } * }}diff --git a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java index c73bd41cea8..517708e70f3 100644 --- a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java +++ b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java @@ -141,6 +141,7 @@ import jdk.internal.vm.annotation.ReservedStackAccess; * * void processCachedData() { * rwl.readLock().lock(); + * // Code between the lock() above, and the unlock() below must not throw * if (!cacheValid) { * // Must release read lock before acquiring write lock * rwl.readLock().unlock(); @@ -158,7 +159,7 @@ import jdk.internal.vm.annotation.ReservedStackAccess; * rwl.writeLock().unlock(); // Unlock write, still hold read * } * } - * + * // Make sure that code that could throw is executed inside the try block * try { * use(data); * } finally {