Summary

Specify the minimal JDWP ThreadReference.PopFrames and JDI ThreadReference.popFrames() support for virtual threads.

Problem

JDWP ThreadReference.PopFrames and JDI ThreadReference.popFrames() are allowed to be supported by implementations in a general form but no minimal support is defined by the spec.

Solution

Specify that JDWP ThreadReference.PopFrames and JDI ThreadReference.popFrames() can be used to pop the frames of a virtual thread suspended at an event.

Specification

The JDWP spec includes the following changes below:

The ThreadReference.PopFrames command description is updated to replace the following:

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.

with:

This command may be used to pop frames of a virtual thread when
it is suspended at an event. An implementation may support popping
the frames of a suspended virtual thread in other cases.

The following ThreadReference.PropFrames error code description is updated:

OPAQUE_FRAME
If one or more of the frames to pop is a native
method or its caller is a native method, or the
thread is a virtual thread and the implementation
is unable to pop the frames.

with:

OPAQUE_FRAME
If one or more of the frames to pop is a native
method or its caller is a native method, or the
thread is a suspended virtual thread and the implementation
was unable to pop the frames.

The JDI spec includes the following changes below:

The ThreadReference.popFrames() method description is updated to replace the following:

The target VM may not support, or may only provide limited support,
for popping stack frames 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.

with:

This method may be used to pop frames of a virtual thread when
it is suspended at an event. An implementation may support popping
the frames of a suspended virtual thread in other cases.

The following ThreadReference.popFrames() exception description was modified from:

@throws OpaqueFrameException if this thread is a virtual thread and the
target VM is unable to pop the frames.

to:

@throws OpaqueFrameException if this thread is a suspended virtual thread and the
target VM was unable to pop the frames.

JDWP Spec diffs

diff --git a/src/java.se/share/data/jdwp/jdwp.spec b/src/java.se/share/data/jdwp/jdwp.spec
index a7d489b2813c..0c4c5ed5c24e 100644
--- a/src/java.se/share/data/jdwp/jdwp.spec
+++ b/src/java.se/share/data/jdwp/jdwp.spec
@@ -2692,10 +2692,9 @@ JDWP "Java(tm) Debug Wire Protocol"
         "<code>objectref</code> is added back as well. The Java virtual machine "
         "program counter is restored to the opcode of the invoke instruction."
         "<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 pop frames of a virtual thread when "
+        "it is suspended at an event. An implementation may support popping "
+        "the frames of a suspended virtual thread in other cases."
         "<p>"
         "Since JDWP version 1.4. Requires canPopFrames capability - see "
         "<a href=\"#JDWP_VirtualMachine_CapabilitiesNew\">CapabilitiesNew</a>."
@@ -2713,8 +2712,8 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error NO_MORE_FRAMES)
             (Error OPAQUE_FRAME      "If one or more of the frames to pop is a native "
                                      "method or its caller is a native method, or the "
-                                     "thread is a virtual thread and the implementation "
-                                     "is unable to pop the frames.")
+                                     "thread is a suspended virtual thread and the implementation "
+                                     "was unable to pop the frames.")
             (Error NOT_IMPLEMENTED)
             (Error VM_DEAD)
         )

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 a201e7ed1376..3cf0cb969603 100644
--- a/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java
+++ b/src/jdk.jdi/share/classes/com/sun/jdi/ThreadReference.java
@@ -370,15 +370,14 @@ List<MonitorInfo> ownedMonitorsAndFrames()
      * Thus the target program may
      * proceed differently than the user would expect.
      * <P>
-     * The specified thread must be suspended.
+     * This thread must be suspended.
      * <P>
      * All <code>StackFrame</code> objects for this thread are
      * invalidated.
      * <p>
-     * The target VM may not support, or may only provide limited support,
-     * for popping stack frames 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 pop frames of a virtual thread when
+     * it is suspended at an event. An implementation may support popping
+     * the frames of a suspended virtual thread in other cases.
      * <P>
      * No events are generated by this method.
      * <P>
@@ -403,8 +402,8 @@ List<MonitorInfo> ownedMonitorsAndFrames()
      * @throws java.lang.IllegalArgumentException if <CODE>frame</CODE>
      * is not on this thread's call stack.
      *
-     * @throws OpaqueFrameException if this thread is a virtual thread and the
-     * target VM is unable to pop the frames.
+     * @throws OpaqueFrameException if this thread is a suspended virtual thread and the
+     * target VM was unable to pop the frames.
      *
      * @throws NativeMethodException if one of the frames that would be
      * popped is that of a native method or if the frame previous to