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 {