Summary

Improve the spec of Lookup::ensureInitialized to document the two possible cases when it returns.

Problem

The javadoc does not clearly state the cases when Lookup::ensureInitialized returns as specified JVMS 5.5 and the implementation. In particular, this method returns when the class is being initialized and this method is called by the initializing thread.

Solution

Document the two possible cases when Lookup::ensureInitialized returns.

Specification

Change the spec of java.lang.invoke.MethodHandles.Lookup::ensureInitialized as follows:

--- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
@@ -2781,8 +2781,14 @@
          * to be initialized if it has not been already initialized,
          * as specified in JVMS {@jvms 5.5}.
          *
+         * <p>
+         * This method returns when {@code targetClass} is fully initialized, or
+         * when {@code targetClass} is being initialized by the current thread.
+         *
          * @param targetClass the class to be initialized
-         * @return {@code targetClass} that has been initialized
+         * @return {@code targetClass} that has been initialized, or that is being
+         *         initialized by the current thread.
          *
          * @throws  IllegalArgumentException if {@code targetClass} is a primitive type or {@code void}
          *          or array class