Summary

JDI spec needs to clarify when OpaqueFrameException and NativeMethodException are thrown

Problem

There is a long standing issue with JDI throwing NativeMethodException for reasons other than a native method. This happens with the ThreadReference popFrames() and forceEarlyReturn() APIs. At the JVMTI level, these APIs can produce JVMTI_ERROR_OPAQUE_FRAME, which is converted to a JDWP OPAQUE_FRAME error. JDI assumed that this can only happen due to a native method, so it converted OPAQUE_FRAME error to a NativeMethodException. However, it could happen due to other reasons specific to the JVMTI implementation. Although very rare, one example is an inability to de-opt the method.

With the addition of virtual threads, JDI introduced OpaqueFrameException for popFrames() for forceEarlyReturn(). This is because with virtual threads, there were other reasons why these APIs might fail. Specifically, the thread had to be suspended at a breakpoint to guarantee the API would succeed. Otherwise JVMTI could produce JVMTI_ERROR_OPAQUE_FRAME, and JDI would then throw OpaqueFrameException if it detected that a native method was not the cause of the OPAQUE_FRAME_EXCEPTION. The wording added to the spec was:

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

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

What was not realized at this time was the other possible reasons for JVMTI_ERROR_OPAQUE_FRAME (such as failure to de-opt), so not only was the above description not fully correct for virtual threads, but we also missed the fact that these other JVMTI_ERROR_OPAQUE_FRAME failures could apply to platform threads too.

Solution

An overview of the solution. Alternative solutions may be discussed; links to rationale documents or review threads welcome to provide additional background to reviewers.

Specification

The detailed changes. Acceptable normative formats include inline patches, attached webrevs, and attached specdiffs or apidiffs. The names of attached files are recommended to include a bug id. References to external webservers, such as https://cr.openjdk.org/ and https://git.openjdk.org/, can be provided as informative supplements for the convenience of reviewers, but must be accompanied by a normative form of the specification directly associated with the CSR issue to satisfy archival purposes.