8320652: ThreadInfo.isInNative needs to be updated to say what executing native code means

Reviewed-by: mchung

Author: Alan Bateman

src/java.management/share/classes/java/lang/management/ThreadInfo.java

@@ -25,6 +25,7 @@
 
 package java.lang.management;
 
+import java.lang.foreign.Linker;
 import javax.management.openmbean.ArrayType;
 import javax.management.openmbean.CompositeData;
 import sun.management.ManagementFactoryHelper;
@@ -544,11 +545,21 @@ public boolean isSuspended() {
     }
 
     /**
-     * Tests if the thread associated with this {@code ThreadInfo}
-     * is executing native code via the Java Native Interface (JNI).
-     * The JNI native code does not include
-     * the virtual machine support code or the compiled native
-     * code generated by the virtual machine.
+     * Tests if the thread associated with this {@code ThreadInfo} is executing
+     * native code.
+     *
+     * <p> A thread is considered to be executing native code when it is executing a
+     * native method, executing native code invoked using a {@linkplain
+     * Linker#downcallHandle(java.lang.foreign.FunctionDescriptor, Linker.Option...)
+     * method handle} obtained from the {@linkplain Linker native linker}, or is
+     * <a href="{@docRoot}/../specs/jni/invocation.html#attachcurrentthread">
+     * attached</a> to the VM with the <a href="{@docRoot}/../specs/jni/index.html">
+     * Java Native Interface</a> with no Java frames on its stack.
+     *
+     * <p> Native code does not include Java virtual machine support code,
+     * compiled code generated by the Java virtual machine, or special cases
+     * such as a thread blocked on a <a href="{@docRoot}/../specs/jvmti.html#RawMonitors">
+     * JVM TI raw monitor</a>.
      *
      * @return {@code true} if the thread is executing native code;
      *         {@code false} otherwise.