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 {