Summary

Specify minimal JDWP ThreadReference.ForceEarlyReturn and JDI ThreadReference.forceEarlyReturn() support for virtual threads.

Problem

JDWP ThreadReference.ForceEarlyReturn and JDI ThreadReference.forceEarlyReturn() are allowed to be supported on virtual threads by implementations, but no minimal support is defined by the spec.

Solution

Specify that JDWP ThreadReference.ForceEarlyReturn and JDI ThreadReference.forceEarlyReturn() can be used to force early return from the current frame of a virtual thread suspended at an event.

Specification

The JDWP spec includes the following changes below:

In the specification for ThreadReference.ForceEarlyReturn, the following text:

    "The target VM may not support, or may only provide limited support, for "
    "this command when the thread is a virtual thread. It may, for example, "
    "only support this command when the virtual thread is suspended at a "
    "breakpoint or singlestep event."

is replaced with:

    "This command may be used to force a return from the current frame "
    "of a virtual thread when it is suspended at an event. "
    "An implementation may support forcing a return from the current frame "
    "of a suspended virtual thread in other cases."

And the following error description:

        (Error OPAQUE_FRAME      "Attempted to return early from a frame "
                                 "corresponding to a native method, "
                                 "the thread is a virtual thread and the target "
                                 "VM is unable to force its current frame to return, "
                                 "or the implementation is unable to provide this "
                                 "functionality on this frame.")

Is replaced with the following to clarify that the virtual thread must be suspended:

        (Error OPAQUE_FRAME      "Attempted to return early from a frame "
                                 "corresponding to a native method, "
                                 "the thread is a suspended virtual thread and the target "
                                 "VM is unable to force its current frame to return, "
                                 "or the implementation is unable to provide this "
                                 "functionality on this frame

The JDI spec includes the following changes below:

In the specification for ThreadReference.forceEarlyReturn(), the following text:

 * The target VM may not support, or may only provide limited support,
 * for forcing a method to return when the thread is a virtual thread.
 * It may, for example, only support this operation when the virtual
 * thread is suspended at a breakpoint or singlestep event.

Is replaced with:

 * This method may be used to force a return from the current frame
 * of a virtual thread when it is suspended at an event.
 * An implementation may support forcing a return from the current frame
 * of a suspended virtual thread in other cases.

And the following error description:

 * @throws OpaqueFrameException if this thread is a virtual thread and the
 * target VM is unable to force the method to return.

Is replaced with the following to clarify that the virtual thread must be suspended:

 * @throws OpaqueFrameException if this thread is a suspended virtual thread and the
 * target VM is unable to force the method to return.

JDWP Spec diffs

diff --git a/src/java.se/share/data/jdwp/jdwp.spec b/src/java.se/share/data/jdwp/jdwp.spec
index 0c4c5ed5c24e..323a48e591e7 100644
--- a/src/java.se/share/data/jdwp/jdwp.spec
+++ b/src/java.se/share/data/jdwp/jdwp.spec
@@ -2104,10 +2104,10 @@ JDWP "Java(tm) Debug Wire Protocol"
         "command and resumption of thread execution, the "
         "state of the stack is undefined. "
         "<p>"
-        "The target VM may not support, or may only provide limited support, for "
-        "this command when the thread is a virtual thread. It may, for example, "
-        "only support this command when the virtual thread is suspended at a "
-        "breakpoint or singlestep event."
+        "This command may be used to force a return from the current frame "
+        "of a virtual thread when it is suspended at an event. "
+        "An implementation may support forcing a return from the current frame "
+        "of a suspended virtual thread in other cases."
         "<p>"
         "No further instructions are executed in the called "
         "method. Specifically, finally blocks are not executed. Note: "
@@ -2147,7 +2147,7 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error THREAD_NOT_SUSPENDED)
             (Error OPAQUE_FRAME      "Attempted to return early from a frame "
                                      "corresponding to a native method, "
-                                     "the thread is a virtual thread and the target "
+                                     "the thread is a suspended virtual thread and the target "
                                      "VM is unable to force its current frame to return, "
                                      "or the implementation is unable to provide this "
                                      "functionality on this frame.")

JDI Spec diffs

diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java
index 3cf0cb969603..9a47111677fc 100644
--- a/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java
+++ b/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java
@@ -436,10 +436,10 @@ List<MonitorInfo> ownedMonitorsAndFrames()
      * this method and resumption of thread execution, the
      * state of the stack is undefined.
      * <p>
-     * The target VM may not support, or may only provide limited support,
-     * for forcing a method to return when the thread is a virtual thread.
-     * It may, for example, only support this operation when the virtual
-     * thread is suspended at a breakpoint or singlestep event.
+     * This method may be used to force a return from the current frame
+     * of a virtual thread when it is suspended at an event.
+     * An implementation may support forcing a return from the current frame
+     * of a suspended virtual thread in other cases.
      * <p>
      * No further instructions are executed in the called
      * method. Specifically, finally blocks are not executed. Note:
@@ -484,7 +484,7 @@ List<MonitorInfo> ownedMonitorsAndFrames()
      * @throws IncompatibleThreadStateException if this
      * thread is not suspended.
      *
-     * @throws OpaqueFrameException if this thread is a virtual thread and the
+     * @throws OpaqueFrameException if this thread is a suspended virtual thread and the
      * target VM is unable to force the method to return.
      *
      * @throws NativeMethodException if the frame to be returned from