Summary

This update makes the clarifications for JVMTI_ERROR_OPAQUE_FRAME error code cases consistent.

Problem

Several JVMTI functions can return the JVMTI_ERROR_OPAQUE_FRAME error code. There can be several reasons to return it. The clarifications are inconsistent over different JVMTI functions.

Solution

Polish the impacted JVMTI function specs to make them consistent.

Specification

The following six kinds of JVMTI sections are impacted:

• PopFrame
• NotifyFramePop
• ForceEarlyReturn<Type>
• GetLocal<Type>
• SetLocal<Type>
• General description of the JVMTI_ERROR_OPAQUE_FRAME error code

There changes are:

In PopFrame spec for JVMTI_ERROR_OPAQUE_FRAME case, replace:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
   Called or calling method is a native method.
   The implementation is unable to pop this frame.
</error>
<error id="JVMTI_ERROR_OPAQUE_FRAME">
   The thread is a suspended virtual thread and the implementation
   was unable to pop the current frame.
</error>

with:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The implementation is unable to pop this frame
  (e.g. called or calling method is a native method).
</error>

In NotifyFramePop spec for JVMTI_ERROR_OPAQUE_FRAME case, replace:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The frame at depth is executing a native method.
</error>

with:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  A FramePop event cannot be generated for this frame
  (e.g. the frame at depth is executing a native method). 
</error>

In ForceEarlyReturn<Type> specs (full list if functions: ForceEarlyReturnObject, ForceEarlyReturnint, ForceEarlyReturnLong, ForceEarlyReturnFloat, ForceEarlyReturnDouble, ForceEarlyReturnVoid), for JVMTI_ERROR_OPAQUE_FRAME case, replace:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
   Attempted to return early from a frame corresponding to a native method.
   The thread is a suspended virtual thread and the implementation was
   unable to force its current frame to return.
   Or the implementation is unable to provide
   this functionality on this frame.
</error>

with:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The implementation is unable to force current frame to return
  (e.g. current frame is executing a native method).
</error>

In GetLocal<Type> specs (full list if functions: GetLocalObject, GetLocalInstance, GetLocalint, GetLocalLong, GetLocalFloat, GetLocalDouble), for JVMTI_ERROR_OPAQUE_FRAME case, replace:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  Not a visible frame.
</error>

with:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The implementation is unable to get the frame locals
  (e.g. the frame at depth is executing a native method).
</error>

In SetLocal<Type> specs (full list if functions: SetLocalObject, SetLocalint, SetLocalLong, SetLocalFloat, SetLocalDouble), for JVMTI_ERROR_OPAQUE_FRAME case, replace:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  Not a visible frame.
</error>
<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The thread is a suspended virtual thread and the implementation does not support
  setting the value of locals in the frame of the given depth.
  See Local Variables.
</error>

with:

<error id="JVMTI_ERROR_OPAQUE_FRAME">
  The implementation is unable to set the frame locals
  (e.g. the frame at depth is executing a native method).
</error>

In the general description of the JVMTI_ERROR_OPAQUE_FRAME error code, replace:

<errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
  Information about the frame is not available (e.g. for native frames),
  or the function cannot be performed on the thread's current frame.
</errorid>

with:

<errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
  Information about the frame is not available (e.g. for native frames),
  or the implementation is unable to provide this functionality on this frame.
</errorid>

Link to a webrev with the spec changes:

https://openjdk.github.io/cr/?repo=jdk&pr=26111&range=05