< prev index next >

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

Print this page
*** 26,12 ***
  package java.lang.management;
  
  import java.util.Map;
  
  /**
!  * The management interface for the thread system of
!  * the Java virtual machine.
   *
   * <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
--- 26,17 ---
  package java.lang.management;
  
  import java.util.Map;
  
  /**
!  * 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 ***
   * @since   1.5
   */
  
  public interface ThreadMXBean extends PlatformManagedObject {
      /**
!      * Returns the current number of live threads including both
       * daemon and non-daemon threads.
       *
!      * @return the current number of live threads.
       */
      public int getThreadCount();
  
      /**
!      * Returns the peak live thread count since the Java virtual machine
!      * started or peak was reset.
       *
!      * @return the peak live thread count.
       */
      public int getPeakThreadCount();
  
      /**
!      * Returns the total number of threads created and also started
       * since the Java virtual machine started.
       *
!      * @return the total number of threads started.
       */
      public long getTotalStartedThreadCount();
  
      /**
!      * Returns the current number of live daemon threads.
       *
!      * @return the current number of live daemon threads.
       */
      public int getDaemonThreadCount();
  
      /**
!      * Returns all live thread IDs.
       * 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.
       *
--- 126,47 ---
   * @since   1.5
   */
  
  public interface ThreadMXBean extends PlatformManagedObject {
      /**
!      * 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 platform threads.
       */
      public int getThreadCount();
  
      /**
!      * 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 platform thread count.
       */
      public int getPeakThreadCount();
  
      /**
!      * 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 platform threads started.
       */
      public long getTotalStartedThreadCount();
  
      /**
!      * 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 platform threads that are daemon threads.
       */
      public int getDaemonThreadCount();
  
      /**
!      * 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 ***
       * 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.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the
--- 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 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 ***
       *
       * @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.
       *
       * @throws IllegalArgumentException if {@code id <= 0}.
       * @throws SecurityException if a security manager
       *         exists and the caller does not have
       *         ManagementPermission("monitor").
--- 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 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 ***
       * <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
       * contain {@code null}.  A thread is alive if
!      * it has been started and has not yet died.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the
--- 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 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 terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

*** 260,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.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the
--- 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 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 ***
       * 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.
       *
       * @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
--- 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 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 ***
       * {@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
       * in the returned array.  A thread is alive if
!      * it has been started and has not yet died.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the
--- 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 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 terminated.
       *
       * <p>
       * <b>MBeanServer access</b>:<br>
       * The mapped type of {@code ThreadInfo} is
       * {@code CompositeData} with attributes as specified in the

*** 448,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
       * is disabled, this method returns {@code -1}.
!      * A thread is alive if it has been started and has not yet died.
       * <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.
--- 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 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 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 ***
       * 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
       * is disabled, this method returns {@code -1}.
!      * A thread is alive if it has been started and has not yet died.
       * <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.
--- 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 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 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 ***
       * </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
       * in the returned array.  A thread is alive if
!      * it has been started and has not yet died.
       * <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},
--- 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 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 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 ***
      }
  
      /**
       * Returns the thread info for all live threads with stack trace
       * and synchronization information.
!      * This is equivalent to calling:
       * <blockquote>
       * {@link #dumpAllThreads(boolean, boolean, int)
       * dumpAllThreads(lockedMonitors, lockedSynchronizers, Integer.MAX_VALUE)}
       * </blockquote>
       *
--- 835,12 ---
      }
  
      /**
       * Returns the thread info for all live threads with stack trace
       * and synchronization information.
!      * 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 >