Summary

java.lang.management.ThreadMXBean, and the extension com.sun.management.ThreadMXBean, support the monitoring and management of platform threads. These APIs do not support virtual threads as their potential number, and the need to map thread id to thread, does make sense for these APIs. The javadoc for the methods that get the CPU time, user time, and #bytes allocated, need to specify how these methods behave when called from a virtual thread or with the thread ID of a virtual thread.

Problem

A number of methods defined by ThreadMXBean do not clearly specify how they behave when invoked from a virtual thread or with the thread ID of a virtual thread.

Solution

Update the "Thread CPU time" section of the ThreadMXBean class description to make it clearer that measuring the CPU time is limited to platform threads. Update the specification of the following methods to make it clear how they behave with virtual threads.

• java.lang.management.ThreadMXBean.getCurrentThreadCpuTime()
• java.lang.management.ThreadMXBean.getCurrentThreadUserTime()
• java.lang.management.ThreadMXBean.getThreadCpuTime(long[ ])
• java.lang.management.ThreadMXBean.getThreadUserTime(long [ ])
• java.lang.management.ThreadMXBean.isThreadCpuTimeSupported()
• java.lang.management.ThreadMXBean.isCurrentThreadCpuTimeSupported()
• com.sun.management.ThreadMXBean.getThreadCpuTime(long[ ])
• com.sun.management.ThreadMXBean.getThreadUserTime(long[ ])
• com.sun.management.ThreadMXBean.getThreadAllocatedBytes(long)

Specification

java.lang.management.ThreadMXBean class description.

-  * A Java virtual machine implementation may support measuring
-  * the CPU time for the current thread, for any thread, or for no threads.
+  * A Java virtual machine implementation may support measuring the CPU time
+  * for the current platform thread, for any platform thread, or for no threads.
   *
   * <p>
   * The {@link #isThreadCpuTimeSupported} method can be used to determine
   * if a Java virtual machine supports measuring of the CPU time for any
-  * thread.  The {@link #isCurrentThreadCpuTimeSupported} method can
-  * be used to determine if a Java virtual machine supports measuring of
-  * the CPU time for the current  thread.
-  * A Java virtual machine implementation that supports CPU time measurement
-  * for any thread will also support that for the current thread.
+  * platform thread.  The {@link #isCurrentThreadCpuTimeSupported()} method
+  * can be used to determine if a Java virtual machine supports measuring of
+  * the CPU time with the {@link #getCurrentThreadCpuTime()} and
+  * {@link #getCurrentThreadUserTime()} methods from a platform thread.

java.lang.management.getCurrentThreadCpuTime()

-      * @return the total CPU time for the current thread if CPU time
-      * measurement is enabled; {@code -1} otherwise.
+      * @return the total CPU time for the current thread if the current
+      * thread is a platform thread and if CPU time measurement is enabled;
+      * {@code -1} otherwise.

java.lang.management.getCurrentThreadUserTime()

-      * @return the user-level CPU time for the current thread if CPU time
-      * measurement is enabled; {@code -1} otherwise.
+      * @return the user-level CPU time for the current thread if the current
+      * thread is a platform thread and if CPU time measurement is enabled;
+      * {@code -1} otherwise.

java.lang.management.getThreadUserTime(long)

-      * @return the total CPU time for a thread of the specified ID
-      * if the thread of the specified ID exists, the thread is alive,
+      * @return the total CPU time for a thread of the specified ID if the
+      * thread of the specified ID is a platform thread, the thread is alive,
       * and CPU time measurement is enabled;
       * {@code -1} otherwise.

java.lang.management.getThreadUserTime(long)

-      * @return the user-level CPU time for a thread of the specified ID
-      * if the thread of the specified ID exists, the thread is alive,
+      * @return the user-level CPU time for a thread of the specified ID if the
+      * thread of the specified ID is a platform thread, the thread is alive,
       * and CPU time measurement is enabled;
       * {@code -1} otherwise.

java.lang.management.isThreadCpuTimeSupported()

       * Tests if the Java virtual machine implementation supports CPU time
-      * measurement for any thread.
+      * measurement for any platform thread.
       * A Java virtual machine implementation that supports CPU time
-      * measurement for any thread will also support CPU time
-      * measurement for the current thread.
+      * measurement for any platform thread will also support CPU time
+      * measurement for the current thread, when the current thread is a
+      * platform thread.
       *
       * @return
       *   {@code true}
       *     if the Java virtual machine supports CPU time
-      *     measurement for any thread;
+      *     measurement for any platform thread;
       *   {@code false} otherwise.

java.lang.management.isCurrentThreadCpuTimeSupported()

-      * Tests if the Java virtual machine supports CPU time
-      * measurement for the current thread.
+      * Tests if the Java virtual machine supports CPU time measurement from
+      * a platform thread with the {@link #getCurrentThreadCpuTime()} and
+      * {@link #getCurrentThreadUserTime()} methods.
       * This method returns {@code true} if {@link #isThreadCpuTimeSupported}
       * returns {@code true}.
       *
       * @return
       *   {@code true}
-      *     if the Java virtual machine supports CPU time
-      *     measurement for current thread;
+      *     if the Java virtual machine supports CPU time measurement
+      *     of the current platform thread;
       *   {@code false} otherwise.

com.sun.management.ThreadMXBean.getThreadCpuTime(long[])

       * @return an array of long values, each of which is the amount of CPU
       * time the thread whose ID is in the corresponding element of the input
-      * array of IDs has used,
-      * if the thread of a specified ID exists, the thread is alive,
-      * and CPU time measurement is enabled;
+      * array of IDs has used, if the thread of a specified ID is a platform
+      * thread, the thread is alive, and CPU time measurement is enabled;
       * {@code -1} otherwise.

com.sun.management.ThreadMXBean.getThreadUserTime(long[])

       * @return an array of long values, each of which is the amount of user
       * mode CPU time the thread whose ID is in the corresponding element of
-      * the input array of IDs has used,
-      * if the thread of a specified ID exists, the thread is alive,
-      * and CPU time measurement is enabled;
+      * the input array of IDs has used, if the thread of a specified ID is a
+      * platform thread, the thread is alive, and CPU time measurement is enabled;
       * {@code -1} otherwise.

com.sun.management.ThreadMXBean.getThreadAllocatedBytes(long)

       * @return an approximation of the total memory allocated, in bytes, in
-      * heap memory for the thread with the specified ID
-      * if the thread with the specified ID exists, the thread is alive,
-      * and thread memory allocation measurement is enabled;
-      * {@code -1} otherwise.
+      * heap memory for the thread with the specified ID if the thread with the
+      * specified ID is a platform thread, the thread is alive, and thread memory
+      * allocation measurement is enabled; {@code -1} otherwise.