Spec updates to get consistent view of threads

Author: AlanBateman

make/data/jdwp/jdwp.spec

@@ -92,7 +92,9 @@ JDWP "Java(tm) Debug Wire Protocol"
         )
     )
     (Command AllThreads=4
-        "Returns all threads currently running in the target VM . "
+        "Returns the live threads in the target VM. "
+        "The returned list contains all live threads that are attached to the VM. "
+        "It does not contain virtual threads. "
         "The returned list contains threads created through "
         "java.lang.Thread, all native threads attached to "
         "the target VM through JNI, and system threads created "
@@ -2188,10 +2190,11 @@ JDWP "Java(tm) Debug Wire Protocol"
     )
     (Command Children=3
         "Returns the live threads and active thread groups directly contained "
-        "in this thread group. Threads and thread groups in child "
+        "in this thread group. Virtual threads are not considered live threads "
+        "in a thread group and are not included. Threads and thread groups in child "
         "thread groups are not included. "
         "A thread is alive if it has been started and has not yet been stopped. "
-        "See <a href=../../api/java.base/java/lang/ThreadGroup.html>java.lang.ThreadGroup </a>
+        "See <a href=../../api/java.base/java/lang/ThreadGroup.html>java.lang.ThreadGroup </a> "
         "for information about active ThreadGroups.
         (Out
             (threadGroupObject group "The thread group object ID. ")

src/hotspot/share/prims/jvmti.xml

@@ -1513,16 +1513,15 @@ jvmtiEnv *jvmti;
     <function id="GetAllThreads" num="4">
       <synopsis>Get All Threads</synopsis>
       <description>
-        Get all live threads.
-        The threads are Java programming language threads;
-        that is, threads that are attached to the VM.
+        Get all live threads that are attached to the VM.
+        The list of threads includes
+        <internallink id="RunAgentThread">agent threads</internallink>.
+        It does not include virtual threads.
         A thread is live if <code>java.lang.Thread.isAlive()</code>
         would return <code>true</code>, that is, the thread has
         been started and has not yet died.
         The universe of threads is determined by the context of the <jvmti/>
         environment, which typically is all threads attached to the VM.
-        Note that this includes <jvmti/> agent threads
-        (see <functionlink id="RunAgentThread"/>).
       </description>
       <origin>jvmdi</origin>
       <capabilities>
@@ -1531,14 +1530,14 @@ jvmtiEnv *jvmti;
         <param id="threads_count_ptr">
           <outptr><jint/></outptr>
           <description>
-            On return, points to the number of running threads.
+            On return, points to the number of threads.
           </description>
         </param>
         <param id="threads_ptr">
           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
             <description>
               On return, points to an array of references, one
-              for each running thread.
+              for each thread.
             </description>
         </param>
       </parameters>
@@ -2433,6 +2432,8 @@ jvmtiEnv *jvmti;
       <synopsis>Get Thread Group Children</synopsis>
       <description>
         Get the live threads and the child thread groups in this thread group.
+        Virtual threads are not considered live threads in a thread group
+        and not returned by this function.
       </description>
       <origin>jvmdi</origin>
       <capabilities>
@@ -2652,8 +2653,11 @@ if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
     <function id="GetAllStackTraces" num="100">
       <synopsis>Get All Stack Traces</synopsis>
       <description>
-        Get information about the stacks of all live threads
-        (including <internallink id="RunAgentThread">agent threads</internallink>).
+        Get the stack traces of all live threads attached to the VM.
+        The list includes the stack traces of
+        <internallink id="RunAgentThread">agent threads</internallink>.
+        It does not include the stack traces of virtual threads.
+        <p/>
         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
         otherwise the entire stack is returned.

src/java.base/share/classes/java/lang/Thread.java

@@ -2658,8 +2658,8 @@ StackTraceElement[] asyncGetStackTrace() {
     private native Object getStackTrace0();
 
     /**
-     * Returns a map of stack traces for all live threads. The map does not
-     * include virtual threads.
+     * Returns a map of stack traces for all live threads that are scheduled
+     * by the operating system. The map does not include virtual threads.
      * The map keys are threads and each map value is an array of
      * {@code StackTraceElement} that represents the stack dump
      * of the corresponding {@code Thread}.

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

@@ -32,10 +32,9 @@
  * the Java virtual machine.
  *
  * <p> {@code ThreadMXBean} supports monitoring and management of <em>live
- * threads</em> in the Java virtual machine. <em>Live threads</em> are threads
- * scheduled by the operating system that have been started but have not yet
- * terminated. {@code ThreadMXBean} does not support monitoring or management
- * of {@linkplain Thread#isVirtual() virtual threads}.
+ * threads</em> in the Java virtual machine that are scheduled by the operating
+ * system. {@code ThreadMXBean} does not support monitoring or management
+ * of {@linkplain Thread#isVirtual() virtual threads} at this time.
  *
  * <p> A Java virtual machine has a single instance of the implementation
  * class of this interface.  This instance implementing this interface is
@@ -131,6 +130,7 @@ public interface ThreadMXBean extends PlatformManagedObject {
     /**
      * Returns the current number of live threads including both
      * daemon and non-daemon threads.
+     * The count does not include virtual threads.
      *
      * @return the current number of live threads.
      */
@@ -139,6 +139,7 @@ public interface ThreadMXBean extends PlatformManagedObject {
     /**
      * Returns the peak live thread count since the Java virtual machine
      * started or peak was reset.
+     * The count does not include virtual threads.
      *
      * @return the peak live thread count.
      */
@@ -147,20 +148,23 @@ public interface ThreadMXBean extends PlatformManagedObject {
     /**
      * Returns the total number of threads created and also started
      * since the Java virtual machine started.
+     * The count does not include virtual threads.
      *
      * @return the total number of threads started.
      */
     public long getTotalStartedThreadCount();
 
     /**
      * Returns the current number of live daemon threads.
+     * The count does not include virtual threads.
      *
      * @return the current number of live daemon threads.
      */
     public int getDaemonThreadCount();
 
     /**
      * Returns all live thread IDs.
+     * The thread IDs of virtual threads are not included.
      * Some threads included in the returned array
      * may have been terminated when this method returns.
      *
@@ -607,6 +611,8 @@ public interface ThreadMXBean extends PlatformManagedObject {
      * the {@link #findDeadlockedThreads findDeadlockedThreads} method
      * should be used.
      *
+     * @apiNote TBD, need to specify behavior for virtual threads.
+     *
      * @return an array of IDs of the threads that are monitor
      * deadlocked, if any; {@code null} otherwise.
      *
@@ -644,6 +650,8 @@ public interface ThreadMXBean extends PlatformManagedObject {
      * This method is designed for troubleshooting use, but not for
      * synchronization control.  It might be an expensive operation.
      *
+     * @apiNote TBD, need to specify behavior for virtual threads.
+     *
      * @return an array of IDs of the threads that are
      * deadlocked waiting for object monitors or ownable synchronizers, if any;
      * {@code null} otherwise.
@@ -829,7 +837,8 @@ public default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
     /**
      * Returns the thread info for all live threads with stack trace
      * and synchronization information.
-     * This is equivalent to calling:
+     * The thread IDs of virtual threads are not included.
+     * This method is equivalent to calling:
      * <blockquote>
      * {@link #dumpAllThreads(boolean, boolean, int)
      * dumpAllThreads(lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
@@ -870,6 +879,7 @@ public default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors,
      * and synchronization information.
      * if {@code maxDepth == 0}, no stack trace of the thread
      * will be dumped.
+     * The thread IDs of virtual threads are not included.
      * Some threads included in the returned array
      * may have been terminated when this method returns.
      *

src/jdk.jdi/share/classes/com/sun/jdi/ThreadGroupReference.java

@@ -79,9 +79,10 @@ public interface ThreadGroupReference extends ObjectReference {
 
     /**
      * Returns a List containing a {@link ThreadReference} for each live thread
-     * in this thread group. Only the live threads in this immediate thread group
-     * (and not its subgroups) are returned.  A thread is alive if it
-     * has been started and has not yet been stopped.
+     * in this thread group. Virtual threads are not considered live threads in
+     * a thread group and are not included. Only the live threads in this
+     * immediate thread group (and not its subgroups) are returned. A thread is
+     * alive if it has been started and has not yet been stopped.
      *
      * @return a List of {@link ThreadReference} objects mirroring the
      * live threads from this thread group in the target VM.

src/jdk.jdi/share/classes/com/sun/jdi/VirtualMachine.java

@@ -250,9 +250,10 @@ default List<ModuleReference> allModules() {
     void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes);
 
     /**
-     * Returns a list of the currently running threads. For each
-     * running thread in the target VM, a {@link ThreadReference}
-     * that mirrors it is placed in the list.
+     * Returns a list of the live threads in the target VM. The returned list
+     * contains a {@link ThreadReference} mirror for each live thread that
+     * is attached to the VM. It does not contain elements for virtual threads.
+     * <p>
      * The returned list contains threads created through
      * java.lang.Thread, all native threads attached to
      * the target VM through JNI, and system threads created