Improved getJObjectValue ducumentation.

src/hotspot/share/jvmci/jvmciCompilerToVM.cpp

@@ -710,6 +710,9 @@ C2V_END
 
 C2V_VMENTRY_0(jlong, getJObjectValue, (JNIEnv* env, jobject, jobject constant_jobject))
     requireNotInHotSpot("getJObjectValue", JVMCI_CHECK_0);
+    if (!THREAD->has_last_Java_frame()) {
+        JVMCI_THROW_MSG_0(IllegalStateException, err_msg("Cannot call getJObjectValue without Java frame anchor"));
+    }
     JVMCIObject constant = JVMCIENV->wrap(constant_jobject);
     Handle constant_value = JVMCIENV->asConstant(constant, JVMCI_CHECK_0);
     jobject jni_handle = JNIHandles::make_local(THREAD, constant_value());

src/jdk.internal.vm.ci/share/classes/jdk/vm/ci/hotspot/HotSpotJVMCIRuntime.java

@@ -925,14 +925,18 @@ JavaType lookupTypeInternal(String name, HotSpotResolvedObjectType accessingType
     }
 
     /**
-     * Gets the {@code jobject} value wrapped by {@code peerObject}. The returned "naked" value is
-     * a JNI local reference, which is valid for the duration of a JVMCI shared library call. This
-     * method must only be called from within the JVMCI shared library.
-     * @param peerObject a reference to an object in the peer runtime
-     * @return the {@code jobject} value wrapped by {@code peerObject}
+     * Gets the {@code jobject} value wrapped by {@code peerObject}. The returned value is
+     * a JNI local reference whose lifetime is scoped by the nearest Java caller (from
+     * HotSpot's perspective). The current thread's state must be {@code _thread_in_native}.
+     * A call from the JVMCI shared library (e.g. libgraal) is in such a state.
+     *
+     * @param peerObject a reference to an object in the HotSpot heap
+     * @return the {@code jobject} value unpacked from {@code peerObject}
      * @throws IllegalArgumentException if the current runtime is not the JVMCI shared library or
-     *             {@code peerObject} is not a peer object reference
+     *             {@code peerObject} is not a HotSpot heap object reference
      * @throws IllegalStateException if not called from within the JVMCI shared library
+     *         or if there is no Java caller frame on the stack
+     *         (i.e., JavaThread::has_last_Java_frame returns false)
      */
     public long getJObjectValue(HotSpotObjectConstant peerObject) {
         return compilerToVm.getJObjectValue((HotSpotObjectConstantImpl)peerObject);