ThreadMXBean (Monitoring and Management Interface for the Java Platform )
Keywords: com.sun.management.ThreadMXBean interface
Date: 2023-01-18

compact3
com.sun.management

## Interface ThreadMXBean

- All Superinterfaces:
    PlatformManagedObject, ThreadMXBean

      @Exported
      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

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default ThreadInfo[]` | `dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)` Returns the thread info for all live threads with stack trace of the specified maximum number of elements and synchronization information.
    `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.
    `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.
    `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.
    `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 inherited from interface java.lang.management.ThreadMXBean

      `dumpAllThreads, findDeadlockedThreads, findMonitorDeadlockedThreads, getAllThreadIds, getCurrentThreadCpuTime, getCurrentThreadUserTime, getDaemonThreadCount, getPeakThreadCount, getThreadCount, getThreadCpuTime, getThreadInfo, getThreadInfo, getThreadInfo, getThreadInfo, getThreadInfo, getThreadUserTime, getTotalStartedThreadCount, isCurrentThreadCpuTimeSupported, isObjectMonitorUsageSupported, isSynchronizerUsageSupported, isThreadContentionMonitoringEnabled, isThreadContentionMonitoringSupported, isThreadCpuTimeEnabled, isThreadCpuTimeSupported, resetPeakThreadCount, setThreadContentionMonitoringEnabled, setThreadCpuTimeEnabled`

    - ### Methods inherited from interface java.lang.management.PlatformManagedObject

      `getObjectName`

- - ### Method Detail

    - #### 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 exists, 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 exists, 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)`

    - #### 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().getId());

      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:
        8u282
      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 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 died.

      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 exists, 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.
        `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("control").
      See Also:
        `isThreadAllocatedMemorySupported()`

    - #### getThreadInfo

          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. If `maxDepth == 0`, no stack trace of the thread will be dumped.

      This method obtains a snapshot of the thread information for each thread including:

      - stack trace of the specified maximum number of elements,
      - the object monitors currently locked by the thread if `lockedMonitors` is `true`, and
      - the ownable synchronizers currently locked by the thread if `lockedSynchronizers` is `true`.

      This method returns an array of the `ThreadInfo` objects, each is the thread information about the thread with the same index as in the `ids` array. If a thread of the given ID is not alive or does not exist, `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.

      If a thread does not lock any object monitor or `lockedMonitors` is `false`, the returned `ThreadInfo` object will have an empty `MonitorInfo` array. Similarly, if a thread does not lock any synchronizer or `lockedSynchronizers` is `false`, the returned `ThreadInfo` object will have an empty `LockInfo` array.

      When both `lockedMonitors` and `lockedSynchronizers` parameters are `false`, it is equivalent to calling:

      >          getThreadInfo(ids, maxDepth)

      This method is designed for troubleshooting use, but not for synchronization control. It might be an expensive operation.

      MBeanServer access:
      The mapped type of `ThreadInfo` is `CompositeData` with attributes as specified in the `ThreadInfo.from` method.

      Parameters:
        `ids` - an array of thread IDs.
        `lockedMonitors` - if `true`, retrieves all locked monitors.
        `lockedSynchronizers` - if `true`, retrieves all locked ownable synchronizers.
        `maxDepth` - indicates the maximum number of `StackTraceElement` to be retrieved from the stack trace.
      Returns:
        an array of the `ThreadInfo` objects, each containing information about a thread whose ID is in the corresponding element of the input array of IDs.
      Throws:
        `IllegalArgumentException` - if `maxDepth` is negative.
        `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").
        `UnsupportedOperationException` -
        - if `lockedMonitors` is `true` but the Java virtual machine does not support monitoring of object monitor usage; or
        - if `lockedSynchronizers` is `true` but the Java virtual machine does not support monitoring of ownable synchronizer usage.
      Since:
        8u282
      See Also:
        `ThreadMXBean.isObjectMonitorUsageSupported()`, `ThreadMXBean.isSynchronizerUsageSupported()`

    - #### dumpAllThreads

          default ThreadInfo[] dumpAllThreads(boolean lockedMonitors,
                                              boolean lockedSynchronizers,
                                              int maxDepth)

      Returns the thread info for all live 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. Some threads included in the returned array may have been terminated when this method returns.

      This method returns an array of `ThreadInfo` objects as specified in the `getThreadInfo(long[], boolean, boolean, int)` method.

      Parameters:
        `lockedMonitors` - if `true`, dump all locked monitors.
        `lockedSynchronizers` - if `true`, dump all locked ownable synchronizers.
        `maxDepth` - indicates the maximum number of `StackTraceElement` to be retrieved from the stack trace.
      Returns:
        an array of `ThreadInfo` for all live threads.
      Throws:
        `IllegalArgumentException` - if `maxDepth` is negative.
        `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").
        `UnsupportedOperationException` -
        - if `lockedMonitors` is `true` but the Java virtual machine does not support monitoring of object monitor usage; or
        - if `lockedSynchronizers` is `true` but the Java virtual machine does not support monitoring of ownable synchronizer usage.
      Since:
        8u282
      See Also:
        `ThreadMXBean.isObjectMonitorUsageSupported()`, `ThreadMXBean.isSynchronizerUsageSupported()`

Copyright © 2003, 2023, Oracle and/or its affiliates. All rights reserved.