ThreadMXBean (Java SE 26 & JDK 26)
Description: declaration: module: jdk.management, package: com.sun.management, interface: ThreadMXBean
Keywords: com.sun.management.ThreadMXBean interface

# Interface ThreadMXBean

All Superinterfaces:
  `PlatformManagedObject, ThreadMXBean`

public interface ThreadMXBean extends ThreadMXBean
Platform-specific management interface for the thread system of the Java virtual machine.

This platform extension is only available to a thread implementation that supports this extension.

Since:
  6u25

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default long`
  `getCurrentThreadAllocatedBytes()`
  Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for the current thread.
  `long`
  `getThreadAllocatedBytes(long id)`
  Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for the thread with the specified ID.
  `long[]`
  `getThreadAllocatedBytes(long[] ids)`
  Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for each thread whose ID is in the input array `ids`.
  `long[]`
  `getThreadCpuTime(long[] ids)`
  Returns the total CPU time for each thread whose ID is in the input array `ids` in nanoseconds.
  `long[]`
  `getThreadUserTime(long[] ids)`
  Returns the CPU time that each thread whose ID is in the input array `ids` has executed in user mode in nanoseconds.
  `default long`
  `getTotalThreadAllocatedBytes()`
  Returns an approximation of the total amount of memory, in bytes, allocated in heap memory by all threads since the Java virtual machine started.
  `boolean`
  `isThreadAllocatedMemoryEnabled()`
  Tests if thread memory allocation measurement is enabled.
  `boolean`
  `isThreadAllocatedMemorySupported()`
  Tests if the Java virtual machine implementation supports thread memory allocation measurement.
  `void`
  `setThreadAllocatedMemoryEnabled(boolean enable)`
  Enables or disables thread memory allocation measurement.

  ### Methods declared in interface PlatformManagedObject

  `getObjectName`
  Modifier and Type
  Method
  Description
  `ObjectName`
  `getObjectName()`
  Returns an `ObjectName` instance representing the object name of this platform managed object.

  ### Methods declared in interface ThreadMXBean

  `dumpAllThreads, dumpAllThreads, findDeadlockedThreads, findMonitorDeadlockedThreads, getAllThreadIds, getCurrentThreadCpuTime, getCurrentThreadUserTime, getDaemonThreadCount, getPeakThreadCount, getThreadCount, getThreadCpuTime, getThreadInfo, getThreadInfo, getThreadInfo, getThreadInfo, getThreadInfo, getThreadInfo, getThreadUserTime, getTotalStartedThreadCount, isCurrentThreadCpuTimeSupported, isObjectMonitorUsageSupported, isSynchronizerUsageSupported, isThreadContentionMonitoringEnabled, isThreadContentionMonitoringSupported, isThreadCpuTimeEnabled, isThreadCpuTimeSupported, resetPeakThreadCount, setThreadContentionMonitoringEnabled, setThreadCpuTimeEnabled`
  Modifier and Type
  Method
  Description
  `ThreadInfo[]`
  `dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers)`
  Returns the thread info for all live platform threads with stack trace and synchronization information.
  `default ThreadInfo[]`
  `dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)`
  Returns the thread info for all live platform threads with stack trace of the specified maximum number of elements and synchronization information. if `maxDepth == 0`, no stack trace of the thread will be dumped.
  `long[]`
  `findDeadlockedThreads()`
  Finds cycles of platform threads that are in deadlock waiting to acquire object monitors or ownable synchronizers.
  `long[]`
  `findMonitorDeadlockedThreads()`
  Finds cycles of platform threads that are in deadlock waiting to acquire object monitors.
  `long[]`
  `getAllThreadIds()`
  Returns the threadIDs of all live platform threads.
  `long`
  `getCurrentThreadCpuTime()`
  Returns the total CPU time for the current thread in nanoseconds.
  `long`
  `getCurrentThreadUserTime()`
  Returns the CPU time that the current thread has executed in user mode in nanoseconds.
  `int`
  `getDaemonThreadCount()`
  Returns the current number of live platform threads that are daemon threads.
  `int`
  `getPeakThreadCount()`
  Returns the peak live platform thread count since the Java virtual machine started or peak was reset.
  `int`
  `getThreadCount()`
  Returns the current number of live platform threads including both daemon and non-daemon threads.
  `long`
  `getThreadCpuTime(long id)`
  Returns the total CPU time for a thread of the specified ID in nanoseconds.
  `ThreadInfo`
  `getThreadInfo(long id)`
  Returns the thread info for a thread of the specified `id` with no stack trace.
  `ThreadInfo[]`
  `getThreadInfo(long[] ids)`
  Returns the thread info for each thread whose ID is in the input array `ids` with no stack trace.
  `ThreadInfo[]`
  `getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers)`
  Returns the thread info for each thread whose ID is in the input array `ids`, with stack trace and synchronization information.
  `default ThreadInfo[]`
  `getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)`
  Returns the thread info for each thread whose ID is in the input array `ids`, with stack trace of the specified maximum number of elements and synchronization information.
  `ThreadInfo[]`
  `getThreadInfo(long[] ids, int maxDepth)`
  Returns the thread info for each thread whose ID is in the input array `ids`, with stack trace of a specified number of stack trace elements.
  `ThreadInfo`
  `getThreadInfo(long id, int maxDepth)`
  Returns a thread info for a thread of the specified `id`, with stack trace of a specified number of stack trace elements.
  `long`
  `getThreadUserTime(long id)`
  Returns the CPU time that a thread of the specified ID has executed in user mode in nanoseconds.
  `long`
  `getTotalStartedThreadCount()`
  Returns the total number of platform threads created and also started since the Java virtual machine started.
  `boolean`
  `isCurrentThreadCpuTimeSupported()`
  Tests if the Java virtual machine supports CPU time measurement from a platform thread with the `ThreadMXBean.getCurrentThreadCpuTime()` and `ThreadMXBean.getCurrentThreadUserTime()` methods.
  `boolean`
  `isObjectMonitorUsageSupported()`
  Tests if the Java virtual machine supports monitoring of object monitor usage.
  `boolean`
  `isSynchronizerUsageSupported()`
  Tests if the Java virtual machine supports monitoring of ownable synchronizer usage.
  `boolean`
  `isThreadContentionMonitoringEnabled()`
  Tests if thread contention monitoring is enabled.
  `boolean`
  `isThreadContentionMonitoringSupported()`
  Tests if the Java virtual machine supports thread contention monitoring.
  `boolean`
  `isThreadCpuTimeEnabled()`
  Tests if thread CPU time measurement is enabled.
  `boolean`
  `isThreadCpuTimeSupported()`
  Tests if the Java virtual machine implementation supports CPU time measurement for any platform thread.
  `void`
  `resetPeakThreadCount()`
  Resets the peak thread count to the current number of live platform threads.
  `void`
  `setThreadContentionMonitoringEnabled(boolean enable)`
  Enables or disables thread contention monitoring.
  `void`
  `setThreadCpuTimeEnabled(boolean enable)`
  Enables or disables thread CPU time measurement.

- ## Method Details

  - ### getThreadCpuTime

    long[] getThreadCpuTime(long[] ids)
    Returns the total CPU time for each thread whose ID is in the input array `ids` in nanoseconds. The returned values are of nanoseconds precision but not necessarily nanoseconds accuracy.

    This method is equivalent to calling the `ThreadMXBean.getThreadCpuTime(long)` method for each thread ID in the input array `ids` and setting the returned value in the corresponding element of the returned array.

    Parameters:
      `ids` - an array of thread IDs.
    Returns:
      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 is a platform thread, the thread is alive, and CPU time measurement is enabled; `-1` otherwise.
    Throws:
      `NullPointerException` - if `ids` is `null`
      `IllegalArgumentException` - if any element in the input array `ids` is `<=` `0`.
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support CPU time measurement.
    See Also:
      - `ThreadMXBean.getThreadCpuTime(long)`
      - `getThreadUserTime(long[])`
      - `ThreadMXBean.isThreadCpuTimeSupported()`
      - `ThreadMXBean.isThreadCpuTimeEnabled()`
      - `ThreadMXBean.setThreadCpuTimeEnabled(boolean)`

  - ### getThreadUserTime

    long[] getThreadUserTime(long[] ids)
    Returns the CPU time that each thread whose ID is in the input array `ids` has executed in user mode in nanoseconds. The returned values are of nanoseconds precision but not necessarily nanoseconds accuracy.

    This method is equivalent to calling the `ThreadMXBean.getThreadUserTime(long)` method for each thread ID in the input array `ids` and setting the returned value in the corresponding element of the returned array.

    Parameters:
      `ids` - an array of thread IDs.
    Returns:
      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 is a platform thread, the thread is alive, and CPU time measurement is enabled; `-1` otherwise.
    Throws:
      `NullPointerException` - if `ids` is `null`
      `IllegalArgumentException` - if any element in the input array `ids` is `<=` `0`.
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support CPU time measurement.
    See Also:
      - `ThreadMXBean.getThreadUserTime(long)`
      - `getThreadCpuTime(long[])`
      - `ThreadMXBean.isThreadCpuTimeSupported()`
      - `ThreadMXBean.isThreadCpuTimeEnabled()`
      - `ThreadMXBean.setThreadCpuTimeEnabled(boolean)`

  - ### getTotalThreadAllocatedBytes

    default long getTotalThreadAllocatedBytes()
    Returns an approximation of the total amount of memory, in bytes, allocated in heap memory by all threads since the Java virtual machine started. The returned value is an approximation because some Java virtual machine implementations may use object allocation mechanisms that result in a delay between the time an object is allocated and the time its size is recorded.
    Implementation Requirements:
      The default implementation throws `UnsupportedOperationException` if the Java virtual machine implementation does not support thread memory allocation measurement, and otherwise acts as though thread memory allocation measurement is disabled.
    Returns:
      an approximation of the total memory allocated, in bytes, in heap memory since the Java virtual machine was started, if thread memory allocation measurement is enabled; `-1` otherwise.
    Throws:
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support thread memory allocation measurement.
    Since:
      21
    See Also:
      - `isThreadAllocatedMemorySupported()`
      - `isThreadAllocatedMemoryEnabled()`
      - `setThreadAllocatedMemoryEnabled(boolean)`

  - ### getCurrentThreadAllocatedBytes

    default long getCurrentThreadAllocatedBytes()
    Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for the current thread. The returned value is an approximation because some Java virtual machine implementations may use object allocation mechanisms that result in a delay between the time an object is allocated and the time its size is recorded.

    This is a convenience method for local management use and is equivalent to calling:

    >       getThreadAllocatedBytes(Thread.currentThread().threadId());

    Returns:
      an approximation of the total memory allocated, in bytes, in heap memory for the current thread if thread memory allocation measurement is enabled; `-1` otherwise.
    Throws:
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support thread memory allocation measurement.
    Since:
      14
    See Also:
      - `isThreadAllocatedMemorySupported()`
      - `isThreadAllocatedMemoryEnabled()`
      - `setThreadAllocatedMemoryEnabled(boolean)`

  - ### getThreadAllocatedBytes

    long getThreadAllocatedBytes(long id)
    Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for the thread with the specified ID. The returned value is an approximation because some Java virtual machine implementations may use object allocation mechanisms that result in a delay between the time an object is allocated and the time its size is recorded.

    If the thread with the specified ID is a virtual thread, is not alive, or does not exist, this method returns `-1`. If thread memory allocation measurement is disabled, this method returns `-1`. A thread is alive if it has been started and has not yet terminated.

    If thread memory allocation 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 thread memory allocation measurement starts.

    Parameters:
      `id` - the thread ID of a thread
    Returns:
      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 is a platform thread, the thread is alive, and thread memory allocation measurement is enabled; `-1` otherwise.
    Throws:
      `IllegalArgumentException` - if `id` `<=` `0`.
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support thread memory allocation measurement.
    See Also:
      - `isThreadAllocatedMemorySupported()`
      - `isThreadAllocatedMemoryEnabled()`
      - `setThreadAllocatedMemoryEnabled(boolean)`

  - ### getThreadAllocatedBytes

    long[] getThreadAllocatedBytes(long[] ids)
    Returns an approximation of the total amount of memory, in bytes, allocated in heap memory for each thread whose ID is in the input array `ids`. The returned values are approximations because some Java virtual machine implementations may use object allocation mechanisms that result in a delay between the time an object is allocated and the time its size is recorded.

    This method is equivalent to calling the `getThreadAllocatedBytes(long)` method for each thread ID in the input array `ids` and setting the returned value in the corresponding element of the returned array.

    Parameters:
      `ids` - an array of thread IDs.
    Returns:
      an array of long values, each of which is an approximation of the total memory allocated, in bytes, in heap memory for the thread whose ID is in the corresponding element of the input array of IDs.
    Throws:
      `NullPointerException` - if `ids` is `null`
      `IllegalArgumentException` - if any element in the input array `ids` is `<=` `0`.
      `UnsupportedOperationException` - if the Java virtual machine implementation does not support thread memory allocation measurement.
    See Also:
      - `getThreadAllocatedBytes(long)`
      - `isThreadAllocatedMemorySupported()`
      - `isThreadAllocatedMemoryEnabled()`
      - `setThreadAllocatedMemoryEnabled(boolean)`

  - ### isThreadAllocatedMemorySupported

    boolean isThreadAllocatedMemorySupported()
    Tests if the Java virtual machine implementation supports thread memory allocation measurement.
    Returns:
      `true` if the Java virtual machine implementation supports thread memory allocation measurement; `false` otherwise.

  - ### isThreadAllocatedMemoryEnabled

    boolean isThreadAllocatedMemoryEnabled()
    Tests if thread memory allocation measurement is enabled.
    Returns:
      `true` if thread memory allocation measurement is enabled; `false` otherwise.
    Throws:
      `UnsupportedOperationException` - if the Java virtual machine does not support thread memory allocation measurement.
    See Also:
      - `isThreadAllocatedMemorySupported()`

  - ### setThreadAllocatedMemoryEnabled

    void setThreadAllocatedMemoryEnabled(boolean enable)
    Enables or disables thread memory allocation measurement. The default is platform dependent.
    Parameters:
      `enable` - `true` to enable; `false` to disable.
    Throws:
      `UnsupportedOperationException` - if the Java virtual machine does not support thread memory allocation measurement.
    See Also:
      - `isThreadAllocatedMemorySupported()`