< prev index next >

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

Print this page
@@ -26,12 +26,17 @@
  package java.lang.management;
  
  import java.util.Map;
  
  /**
-  * The management interface for the thread system of
-  * the Java virtual machine.
+  * The management interface for the thread system of the Java virtual machine.
+  *
+  * <p> {@code ThreadMXBean} supports monitoring and management of <em>live
+  * platform threads</em> in the Java virtual machine. Platform threads are
+  * typically mapped to kernel threads scheduled by the operating system.
+  * {@code ThreadMXBean} does not support monitoring or management of {@linkplain
+  * Thread#isVirtual() virtual threads}.
   *
   * <p> A Java virtual machine has a single instance of the implementation
   * class of this interface.  This instance implementing this interface is
   * an <a href="ManagementFactory.html#MXBean">MXBean</a>
   * that can be obtained by calling

@@ -121,42 +126,47 @@
   * @since   1.5
   */
  
  public interface ThreadMXBean extends PlatformManagedObject {
      /**
-      * Returns the current number of live threads including both
+      * Returns the current number of live platform threads including both
       * daemon and non-daemon threads.
+      * The count does not include virtual threads.
       *
-      * @return the current number of live threads.
+      * @return the current number of live platform threads.
       */
      public int getThreadCount();
  
      /**
-      * Returns the peak live thread count since the Java virtual machine
-      * started or peak was reset.
+      * Returns the peak live platform 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.
+      * @return the peak live platform thread count.
       */
      public int getPeakThreadCount();
  
      /**
-      * Returns the total number of threads created and also started
+      * Returns the total number of platform 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.
+      * @return the total number of platform threads started.
       */
      public long getTotalStartedThreadCount();
  
      /**
-      * Returns the current number of live daemon threads.
+      * Returns the current number of live platform threads that are daemon threads.
+      * The count does not include virtual threads.
       *
-      * @return the current number of live daemon threads.
+      * @return the current number of live platform threads that are daemon threads.
       */
      public int getDaemonThreadCount();
  
      /**
-      * Returns all live thread IDs.
+      * Returns the threadIDs of all live platform threads.
+      * The thread IDs of virtual threads are not included.
       * Some threads included in the returned array
       * may have been terminated when this method returns.
       *
       * @return an array of {@code long}, each is a thread ID.
       *

@@ -179,13 +189,13 @@
       * the thread information for the thread of the specified ID.
       * The stack trace, locked monitors, and locked synchronizers
       * in the returned {@code ThreadInfo} object will
       * be empty.
       *
-      * If a thread of the given ID is not alive or does not exist,
-      * this method will return {@code null}.  A thread is alive if
-      * it has been started and has not yet died.
+      * If a thread of the given ID is a virtual thread, is not alive, or does
+      * not exist, then this method will return {@code null}. A thread is
+      * alive if it has been started and has not yet terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

@@ -193,12 +203,12 @@
       *
       * @param id the thread ID of the thread. Must be positive.
       *
       * @return a {@link ThreadInfo} object for the thread of the given ID
       * with no stack trace, no locked monitor and no synchronizer info;
-      * {@code null} if the thread of the given ID is not alive or
-      * it does not exist.
+      * {@code null} if the thread of the given ID is a virtual thread,
+      * is not alive, or it does not exist.
       *
       * @throws IllegalArgumentException if {@code id <= 0}.
       * @throws SecurityException if a security manager
       *         exists and the caller does not have
       *         ManagementPermission("monitor").

@@ -216,14 +226,14 @@
       * <p>
       * This method returns an array of the {@code ThreadInfo} objects.
       * The stack trace, locked monitors, and locked synchronizers
       * in each {@code ThreadInfo} object will be empty.
       *
-      * If a thread of a given ID is not alive or does not exist,
-      * the corresponding element in the returned array will
+      * If a thread of the given ID is a virtual thread, is not alive, or does
+      * not exist, the corresponding element in the returned array will
       * contain {@code null}.  A thread is alive if
-      * it has been started and has not yet died.
+      * it has been started and has not yet terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

@@ -260,13 +270,13 @@
       * the stack trace in the
       * {@code ThreadInfo} object will be an empty array of
       * {@code StackTraceElement}.
       *
       * <p>
-      * If a thread of the given ID is not alive or does not exist,
-      * this method will return {@code null}.  A thread is alive if
-      * it has been started and has not yet died.
+      * If a thread of the given ID is a virtual thread, is not alive, or does
+      * not exist, this method will return {@code null}. A thread is alive if
+      * it has been started and has not yet terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

@@ -277,12 +287,12 @@
       * to be dumped. {@code Integer.MAX_VALUE} could be used to request
       * the entire stack to be dumped.
       *
       * @return a {@link ThreadInfo} of the thread of the given ID
       * with no locked monitor and synchronizer info.
-      * {@code null} if the thread of the given ID is not alive or
-      * it does not exist.
+      * {@code null} if the thread of the given ID is a virtual thread, is
+      * not alive or it does not exist.
       *
       * @throws IllegalArgumentException if {@code id <= 0}.
       * @throws IllegalArgumentException if {@code maxDepth is negative}.
       * @throws SecurityException if a security manager
       *         exists and the caller does not have

@@ -311,14 +321,14 @@
       * {@code StackTraceElement}.
       * <p>
       * This method returns an array of the {@code ThreadInfo} objects,
       * each is the thread information about the thread with the same index
       * as in the {@code ids} array.
-      * If a thread of the given ID is not alive or does not exist,
-      * {@code null} will be set in the corresponding element
+      * If a thread of the given ID is a virtual thread, is not alive, or does
+      * not exist, {@code null} will be set in the corresponding element
       * in the returned array.  A thread is alive if
-      * it has been started and has not yet died.
+      * it has been started and has not yet terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

@@ -448,14 +458,14 @@
       * If the implementation distinguishes between user mode time and system
       * mode time, the returned CPU time is the amount of time that
       * the thread has executed in user mode or system mode.
       *
       * <p>
-      * If the thread of the specified ID is not alive or does not exist,
-      * this method returns {@code -1}. If CPU time measurement
+      * If the thread of the specified ID is a virtual thread, is not alive or
+      * does not exist, this method returns {@code -1}. If CPU time measurement
       * is disabled, this method returns {@code -1}.
-      * A thread is alive if it has been started and has not yet died.
+      * A thread is alive if it has been started and has not yet terminated.
       * <p>
       * If CPU time measurement is enabled after the thread has started,
       * the Java virtual machine implementation may choose any time up to
       * and including the time that the capability is enabled as the point
       * where CPU time measurement starts.

@@ -483,14 +493,14 @@
       * has executed in user mode in nanoseconds.
       * The returned value is of nanoseconds precision but
       * not necessarily nanoseconds accuracy.
       *
       * <p>
-      * If the thread of the specified ID is not alive or does not exist,
-      * this method returns {@code -1}. If CPU time measurement
+      * If the thread of the specified ID is a virtual thread, is not alive, or
+      * does not exist, this method returns {@code -1}. If CPU time measurement
       * is disabled, this method returns {@code -1}.
-      * A thread is alive if it has been started and has not yet died.
+      * A thread is alive if it has been started and has not yet terminated.
       * <p>
       * If CPU time measurement is enabled after the thread has started,
       * the Java virtual machine implementation may choose any time up to
       * and including the time that the capability is enabled as the point
       * where CPU time measurement starts.

@@ -592,10 +602,12 @@
       * for a monitor owned by thread B, and thread B is blocked waiting
       * for a monitor owned by thread A.
       * <p>
       * This method is designed for troubleshooting use, but not for
       * synchronization control.  It might be an expensive operation.
+      * Its behavior with cycles involving virtual threads is not defined
+      * in this release.
       * <p>
       * This method finds deadlocks involving only object monitors.
       * To find deadlocks involving both object monitors and
       * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>,
       * the {@link #findDeadlockedThreads findDeadlockedThreads} method

@@ -635,10 +647,12 @@
       * trying to acquire another lock already held
       * by another thread in the cycle.
       * <p>
       * This method is designed for troubleshooting use, but not for
       * synchronization control.  It might be an expensive operation.
+      * Its behavior with cycles involving virtual threads is not defined
+      * in this release.
       *
       * @return an array of IDs of the threads that are
       * deadlocked waiting for object monitors or ownable synchronizers, if any;
       * {@code null} otherwise.
       *

@@ -748,14 +762,14 @@
       * </ul>
       * <p>
       * This method returns an array of the {@code ThreadInfo} objects,
       * each is the thread information about the thread with the same index
       * as in the {@code ids} array.
-      * If a thread of the given ID is not alive or does not exist,
-      * {@code null} will be set in the corresponding element
+      * If a thread of the given ID is a virtual thread, is not alive, or does
+      * not exist, {@code null} will be set in the corresponding element
       * in the returned array.  A thread is alive if
-      * it has been started and has not yet died.
+      * it has been started and has not yet terminated.
       * <p>
       * If a thread does not lock any object monitor or {@code lockedMonitors}
       * is {@code false}, the returned {@code ThreadInfo} object will have an
       * empty {@code MonitorInfo} array.  Similarly, if a thread does not
       * lock any synchronizer or {@code lockedSynchronizers} is {@code false},

@@ -821,11 +835,12 @@
      }
  
      /**
       * 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)}
       * </blockquote>
       *

@@ -862,10 +877,11 @@
       * Returns the thread info for all live threads
       * with stack trace of the specified maximum number of elements
       * 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.
       *
       * <p>
       * This method returns an array of {@link ThreadInfo} objects
< prev index next >