Interface ThreadMXBean

All Superinterfaces:
PlatformManagedObject
All Known Subinterfaces:
ThreadMXBean

public interface ThreadMXBean extends PlatformManagedObject
The management and monitoring interface for the threading system of the virtual machine.

Precisely one instance of this interface will be made available to management clients.

Accessing this MXBean can be done in one of three ways.

  1. Invoking the static ManagementFactory.getThreadMXBean() method.
  2. Using a javax.management.MBeanServerConnection.
  3. Obtaining a proxy MXBean from the static ManagementFactory.newPlatformMXBeanProxy(javax.management.MBeanServerConnection, java.lang.String, java.lang.Class<T>) method, passing in "java.lang:type=Threading" for the value of the second parameter.
Since:
1.5
  • Method Summary

    Modifier and Type
    Method
    Description
    dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers)
    Returns an array of ThreadInfo objects holding information on all threads that were alive when the call was invoked.
    default ThreadInfo[]
    dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)
    Returns an array of ThreadInfo objects holding information on all threads that were alive when the call was invoked.
    long[]
    If supported by the virtual machine, this method can be used to retrieve the long id of all threads currently waiting on object monitors or ownable synchronizers (synchronizers that make use of the AbstractOwnableSynchronizer type and which are completely owned by a single thread).
    long[]
    Returns the thread identifiers of every thread in this virtual machine that is currently blocked in a deadlock situation over a monitor object.
    long[]
    Returns an array of the identifiers of all of the threads that are alive in the current virtual machine.
    long
    If supported by the virtual machine, returns the total CPU usage time for the currently running thread.
    long
    If supported by the virtual machine, returns the total CPU usage time for the current thread running in user mode.
    int
    Returns the number of daemon threads currently alive in the virtual machine.
    int
    Returns the peak number of threads that have ever been alive in the virtual machine at any one instant since either the virtual machine start-up or the peak was reset.
    int
    Returns the number of threads currently alive in the virtual machine.
    long
    If supported by the virtual machine, returns the total CPU usage time for the thread with the specified identifier.
    getThreadInfo(long id)
    Returns a ThreadInfo object for the thread with the specified identifier.
    getThreadInfo(long[] ids)
    Returns an array of ThreadInfo objects ; one for each of the threads specified in the input array of identifiers.
    getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers)
    Returns an array of ThreadInfo objects; one for each of the threads specified in the ids argument.
    default ThreadInfo[]
    getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)
    Returns an array of ThreadInfo objects; one for each of the threads specified in the ids argument.
    getThreadInfo(long[] ids, int maxDepth)
    Returns an array of ThreadInfo objects ; one for each of the threads specified in the ids argument.
    getThreadInfo(long id, int maxDepth)
    Returns a ThreadInfo object for the thread with the specified identifier.
    long
    If supported by the virtual machine, returns the total CPU usage time for the thread with the specified identifier when running in user mode.
    long
    Returns the number of threads that have been started in this virtual machine since it came into being.
    boolean
    Returns a boolean indication of whether or not the virtual machine supports the CPU timing of the current thread.
    boolean
    Returns a boolean indication of whether or not the virtual machine supports the monitoring of object monitor usage.
    boolean
    Returns a boolean indication of whether or not the virtual machine supports the monitoring of ownable synchronizers (synchronizers that make use of the AbstractOwnableSynchronizer type and which are completely owned by a single thread).
    boolean
    Returns a boolean indication of whether or not the monitoring of thread contention situations is enabled on this virtual machine.
    boolean
    Returns a boolean indication of whether or not the monitoring of thread contention situations is supported on this virtual machine.
    boolean
    Returns a boolean indication of whether or not the CPU timing of threads is enabled on this virtual machine.
    boolean
    Returns a boolean indication of whether or not the virtual machine supports the CPU time measurement of any threads (current or otherwise).
    void
    Resets the peak thread count to be the current number of threads alive in the virtual machine when the call is made.
    void
    Updates the virtual machine to either enable or disable the monitoring of thread contention situations.
    void
    setThreadCpuTimeEnabled(boolean enable)
    If supported, updates the virtual machine to either enable or disable the CPU timing of threads.

    Methods declared in interface java.lang.management.PlatformManagedObject

    getObjectName
  • Method Details

    • findMonitorDeadlockedThreads

      long[] findMonitorDeadlockedThreads()
      Returns the thread identifiers of every thread in this virtual machine that is currently blocked in a deadlock situation over a monitor object. A thread is considered to be deadlocked if it is blocked waiting to run and owns an object monitor that is sought by another blocked thread. Two or more threads can be in a deadlock cycle. To determine the threads currently deadlocked by object monitors and ownable synchronizers use the findDeadlockedThreads() method.

      It is recommended that this method be used solely for problem determination analysis and not as a means of managing thread synchronization in a virtual machine. This is because the method may be very expensive to run.

      Returns:
      an array of the identifiers of every thread in the virtual machine that has been detected as currently being in a deadlock situation over an object monitor. May be null if there are currently no threads in that category.
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
    • getAllThreadIds

      long[] getAllThreadIds()
      Returns an array of the identifiers of all of the threads that are alive in the current virtual machine. When processing the return from this method it should not be assumed that each identified thread is still alive.
      Returns:
      the identifiers of all of the threads currently alive in the virtual machine.
    • getCurrentThreadCpuTime

      long getCurrentThreadCpuTime()
      If supported by the virtual machine, returns the total CPU usage time for the currently running thread. The returned time will have nanosecond precision but may not have nanosecond accuracy.

      Method isCurrentThreadCpuTimeSupported() may be used to determine if current thread CPU timing is supported on the virtual machine. On virtual machines where current thread CPU timing is supported, the method isThreadCpuTimeEnabled() may be used to determine if thread CPU timing is actually enabled.

      The return value is identical to that which would be obtained by calling getThreadCpuTime(long) with an argument Thread.currentThread().getId()).

      Returns:
      on virtual machines where current thread CPU timing is supported and thread CPU timing is enabled, the number of nanoseconds CPU usage by the current thread. On virtual machines where current thread CPU timing is supported but thread CPU timing is not enabled, -1.
      Throws:
      UnsupportedOperationException - if the virtual machine does not support current thread CPU timing.
    • getCurrentThreadUserTime

      long getCurrentThreadUserTime()
      If supported by the virtual machine, returns the total CPU usage time for the current thread running in user mode. The returned time will have nanosecond precision but may not have nanosecond accuracy.

      Method isCurrentThreadCpuTimeSupported() may be used to determine if current thread CPU timing is supported on the virtual machine. On virtual machines where current thread CPU timing is supported, the method isThreadCpuTimeEnabled() may be used to determine if thread CPU timing is actually enabled.

      The return value is identical to that which would be obtained by calling getThreadUserTime(long) with an argument Thread.currentThread().getId()).

      Returns:
      on virtual machines where current thread CPU timing is supported and thread CPU timing is enabled, the number of nanoseconds CPU time used by the current thread running in user mode. On virtual machines where current thread CPU timing is supported but thread CPU timing is not enabled, -1.
      Throws:
      UnsupportedOperationException - if the virtual machine does not support current thread CPU timing.
    • getDaemonThreadCount

      int getDaemonThreadCount()
      Returns the number of daemon threads currently alive in the virtual machine.
      Returns:
      the number of currently alive daemon threads.
    • getPeakThreadCount

      int getPeakThreadCount()
      Returns the peak number of threads that have ever been alive in the virtual machine at any one instant since either the virtual machine start-up or the peak was reset.
      Returns:
      the peak number of live threads
      See Also:
    • getThreadCount

      int getThreadCount()
      Returns the number of threads currently alive in the virtual machine. This includes both daemon threads and non-daemon threads.
      Returns:
      the number of currently alive threads.
    • getThreadCpuTime

      long getThreadCpuTime(long id)
      If supported by the virtual machine, returns the total CPU usage time for the thread with the specified identifier. The returned time will have nanosecond precision but may not have nanosecond accuracy.

      Method isThreadCpuTimeSupported() may be used to determine if the CPU timing of threads is supported on the virtual machine. On virtual machines where current thread CPU timing is supported, the method isThreadCpuTimeEnabled() may be used to determine if thread CPU timing is actually enabled.

      Parameters:
      id - the identifier for a thread. Must be a positive number greater than zero.
      Returns:
      on virtual machines where thread CPU timing is supported and enabled, and there is a living thread with identifier id, the number of nanoseconds CPU time used by the thread. On virtual machines where thread CPU timing is supported but not enabled, or where there is no living thread with identifier id present in the virtual machine, a value of -1 is returned.
      Throws:
      IllegalArgumentException - if id is <=0.
      UnsupportedOperationException - if the virtual machine does not support thread CPU timing.
      See Also:
    • getThreadInfo

      ThreadInfo getThreadInfo(long id)
      Returns a ThreadInfo object for the thread with the specified identifier. The returned object will not have a stack trace so that a call to its getStackTrace() method will result in an empty StackTraceElement array. Similarly, the returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls to getLockedMonitors() and getLockedSynchronizers will both return array values.
      Parameters:
      id - the identifier for a thread. Must be a positive number greater than zero.
      Returns:
      if the supplied id maps to a living thread in the virtual machine (i.e. a started thread which has not yet died), this method returns a ThreadInfo object corresponding to that thread. Otherwise, returns null.
      Throws:
      IllegalArgumentException - if id is <=0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
    • getThreadInfo

      ThreadInfo[] getThreadInfo(long[] ids)
      Returns an array of ThreadInfo objects ; one for each of the threads specified in the input array of identifiers. None of the objects in the return array will have a stack trace so that a call to its getStackTrace() method will result in an empty StackTraceElement array. Similarly, the returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls to getLockedMonitors() and getLockedSynchronizers will both return array values.
      Parameters:
      ids - an array of thread identifiers. Each one must be a positive number greater than zero.
      Returns:
      an array of ThreadInfo objects with each entry corresponding to one of the threads specified in the input array of identifiers. The return array will therefore have an identical number of elements to the input ids array. If an entry in the ids array is invalid (there is no living thread with the supplied identifier in the virtual machine) then the corresponding entry in the return array will be a null.
      Throws:
      IllegalArgumentException - if any of the entries in the ids array is <=0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
    • getThreadInfo

      ThreadInfo[] getThreadInfo(long[] ids, int maxDepth)
      Returns an array of ThreadInfo objects ; one for each of the threads specified in the ids argument. The stack trace information in the returned objects will depend on the value of the maxDepth argument which specifies the maximum number of StackTraceElement instances to try and include. A subsequent call to any of the returned objects' getStackTrace() method should result in a StackTraceElement array of up to maxDepth elements. A maxDepth value of Integer.MAX_VALUE will attempt to obtain all of the stack trace information for each specified thread while a maxDepth value of zero will yield none.

      The returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls to getLockedMonitors() and getLockedSynchronizers will both return array values.

      Parameters:
      ids - an array of thread identifiers. Each must be a positive number greater than zero.
      maxDepth - the maximum number of stack trace entries to be included in each of the returned ThreadInfo objects. Supplying Integer.MAX_VALUE attempts to obtain all of the stack traces. Only a positive value is expected.
      Returns:
      an array of ThreadInfo objects. The size of the array will be identical to that of the ids argument. Null elements will be placed in the array if the corresponding thread identifier in ids does not resolve to a living thread in the virtual machine (i.e. a started thread which has not yet died).
      Throws:
      IllegalArgumentException - if any element in ids is <=0.
      IllegalArgumentException - if maxDepth is <0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
    • getThreadInfo

      ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers)
      Returns an array of ThreadInfo objects; one for each of the threads specified in the ids argument. Each ThreadInfo will hold details of all of the stack trace information for each specified thread. The returned ThreadInfo objects will optionally contain details of all monitor objects and synchronizers locked by the corresponding thread. In order to retrieve locked monitor information the lockedMonitors argument should be set to true; in order to retrieve locked synchronizers information lockedSynchronizers should be set to true. For a given ThreadInfo element of the return array the optional information may be inspected by calling ThreadInfo.getLockedMonitors() and ThreadInfo.getLockedSynchronizers() respectively.

      Both lockedMonitors and lockedSynchronizers arguments should only be set to true if the virtual machine supports the requested monitoring.

      Parameters:
      ids - an array of thread identifiers. Each one must be a positive number greater than zero.
      lockedMonitors - boolean indication of whether or not each returned ThreadInfo should hold information on locked object monitors
      lockedSynchronizers - boolean indication of whether or not each returned ThreadInfo should hold information on locked synchronizers
      Returns:
      an array of ThreadInfo objects with each entry corresponding to one of the threads specified in the input array of identifiers. The return array will therefore have an identical number of elements to the input ids array. If an entry in the ids array is invalid (there is no living thread with the supplied identifier in the virtual machine) then the corresponding entry in the return array will be a null.
      Throws:
      IllegalArgumentException - if any of the entries in the ids array is <=0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
      UnsupportedOperationException - if either of the following conditions apply:
    • getThreadInfo

      ThreadInfo getThreadInfo(long id, int maxDepth)
      Returns a ThreadInfo object for the thread with the specified identifier. The stack trace information in the returned object will depend on the value of the maxDepth argument which specifies the maximum number of StackTraceElement instances to include. A subsequent call to the returned object's getStackTrace() method should then result in a StackTraceElement array of up to maxDepth elements. A maxDepth value of Integer.MAX_VALUE will obtain all of the stack trace information for the thread while a maxDepth value of zero will yield none.

      It is possible that the virtual machine may be unable to supply any stack trace information for the specified thread. In that case the returned ThreadInfo object will have an empty array of StackTraceElements.

      The returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls to getLockedMonitors() and getLockedSynchronizers will both return array values.

      Parameters:
      id - the identifier for a thread. Must be a positive number greater than zero.
      maxDepth - the maximum number of stack trace entries to be included in the returned ThreadInfo object. Supplying Integer.MAX_VALUE obtains all of the stack trace. Only a positive value is expected.
      Returns:
      if the supplied id maps to a living thread in the virtual machine (i.e. a started thread which has not yet died), this method returns a ThreadInfo object corresponding to that thread. Otherwise, returns null.
      Throws:
      IllegalArgumentException - if id is <=0.
      IllegalArgumentException - if maxDepth is <0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
    • getThreadUserTime

      long getThreadUserTime(long id)
      If supported by the virtual machine, returns the total CPU usage time for the thread with the specified identifier when running in user mode. The returned time will have nanosecond precision but may not have nanosecond accuracy.

      Method isThreadCpuTimeSupported() may be used to determine if the CPU timing of threads is supported on the virtual machine. On virtual machines where current thread CPU timing is supported, the method isThreadCpuTimeEnabled() may be used to determine if thread CPU timing is actually enabled.

      Parameters:
      id - the identifier for a thread. Must be a positive number greater than zero.
      Returns:
      on virtual machines where thread CPU timing is supported and enabled, and there is a living thread with identifier id, the number of nanoseconds CPU time used by the thread running in user mode. On virtual machines where thread CPU timing is supported but not enabled, or where there is no living thread with identifier id present in the virtual machine, a value of -1 is returned.

      If thread CPU timing was disabled when the thread was started then the virtual machine is free to choose any measurement start time between when the virtual machine started up and when thread CPU timing was enabled with a call to setThreadCpuTimeEnabled(boolean).

      Throws:
      IllegalArgumentException - if id is <=0.
      UnsupportedOperationException - if the virtual machine does not support thread CPU timing.
      See Also:
    • getTotalStartedThreadCount

      long getTotalStartedThreadCount()
      Returns the number of threads that have been started in this virtual machine since it came into being.
      Returns:
      the total number of started threads.
    • isCurrentThreadCpuTimeSupported

      boolean isCurrentThreadCpuTimeSupported()
      Returns a boolean indication of whether or not the virtual machine supports the CPU timing of the current thread.

      Note that this method must return true if isThreadCpuTimeSupported() returns true.

      Returns:
      true if CPU timing of the current thread is supported, otherwise false.
    • isThreadContentionMonitoringEnabled

      boolean isThreadContentionMonitoringEnabled()
      Returns a boolean indication of whether or not the monitoring of thread contention situations is enabled on this virtual machine.
      Returns:
      true if thread contention monitoring is enabled, false otherwise.
    • isThreadContentionMonitoringSupported

      boolean isThreadContentionMonitoringSupported()
      Returns a boolean indication of whether or not the monitoring of thread contention situations is supported on this virtual machine.
      Returns:
      true if thread contention monitoring is supported, false otherwise.
    • isThreadCpuTimeEnabled

      boolean isThreadCpuTimeEnabled()
      Returns a boolean indication of whether or not the CPU timing of threads is enabled on this virtual machine.
      Returns:
      true if thread CPU timing is enabled, false otherwise.
      Throws:
      UnsupportedOperationException - if the virtual machine does not support thread CPU timing.
      See Also:
    • isThreadCpuTimeSupported

      boolean isThreadCpuTimeSupported()
      Returns a boolean indication of whether or not the virtual machine supports the CPU time measurement of any threads (current or otherwise).
      Returns:
      true if the virtual machine supports the CPU timing of threads, false otherwise.
    • resetPeakThreadCount

      void resetPeakThreadCount()
      Resets the peak thread count to be the current number of threads alive in the virtual machine when the call is made.
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "control".
    • setThreadContentionMonitoringEnabled

      void setThreadContentionMonitoringEnabled(boolean enable)
      Updates the virtual machine to either enable or disable the monitoring of thread contention situations.

      If it is supported, the virtual machine will initially not monitor thread contention situations.

      Parameters:
      enable - enable thread contention monitoring if true, otherwise disable thread contention monitoring.
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "control".
      UnsupportedOperationException - if the virtual machine does not support thread contention monitoring.
      See Also:
    • setThreadCpuTimeEnabled

      void setThreadCpuTimeEnabled(boolean enable)
      If supported, updates the virtual machine to either enable or disable the CPU timing of threads.

      The default value of this property depends on the underlying operating system on which the virtual machine is running.

      Parameters:
      enable - enable thread CPU timing if true, otherwise disable thread CPU timing
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "control".
      UnsupportedOperationException - if the virtual machine does not support thread CPU timing.
      See Also:
    • isObjectMonitorUsageSupported

      boolean isObjectMonitorUsageSupported()
      Returns a boolean indication of whether or not the virtual machine supports the monitoring of object monitor usage.
      Returns:
      true if object monitor usage is permitted, otherwise false
      Since:
      1.6
    • isSynchronizerUsageSupported

      boolean isSynchronizerUsageSupported()
      Returns a boolean indication of whether or not the virtual machine supports the monitoring of ownable synchronizers (synchronizers that make use of the AbstractOwnableSynchronizer type and which are completely owned by a single thread).
      Returns:
      true if synchronizer usage monitoring is permitted, otherwise false
    • findDeadlockedThreads

      long[] findDeadlockedThreads()
      If supported by the virtual machine, this method can be used to retrieve the long id of all threads currently waiting on object monitors or ownable synchronizers (synchronizers that make use of the AbstractOwnableSynchronizer type and which are completely owned by a single thread). To determine the threads currently deadlocked by object monitors only use the findMonitorDeadlockedThreads() method.

      It is recommended that this method be used solely for problem determination analysis and not as a means of managing thread synchronization in a virtual machine. This is because the method may be very expensive to run.

      Returns:
      an array of the identifiers of every thread in the virtual machine that has been detected as currently being in a deadlock situation involving object monitors and ownable synchronizers. If there are no threads in this category a null is returned.
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
      UnsupportedOperationException - if the virtual machine does not support any monitoring of ownable synchronizers.
      See Also:
    • dumpAllThreads

      ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers)
      Returns an array of ThreadInfo objects holding information on all threads that were alive when the call was invoked.
      Parameters:
      lockedMonitors - boolean indication of whether or not information on all currently locked object monitors is to be included in the returned array
      lockedSynchronizers - boolean indication of whether or not information on all currently locked ownable synchronizers is to be included in the returned array
      Returns:
      an array of ThreadInfo objects
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
      UnsupportedOperationException - if either of the following conditions apply:
    • dumpAllThreads

      default ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)
      Returns an array of ThreadInfo objects holding information on all threads that were alive when the call was invoked.
      Parameters:
      lockedMonitors - boolean indication of whether or not information on all currently locked object monitors is to be included in the returned array
      lockedSynchronizers - boolean indication of whether or not information on all currently locked ownable synchronizers is to be included in the returned array
      maxDepth - limits the number of stack frames returned
      Returns:
      an array of ThreadInfo objects
      Throws:
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
      UnsupportedOperationException - if either of the following conditions apply:
      Since:
      10
    • getThreadInfo

      default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth)
      Returns an array of ThreadInfo objects; one for each of the threads specified in the ids argument. Each ThreadInfo will hold details of all of the stack trace information for each specified thread. The returned ThreadInfo objects will optionally contain details of all monitor objects and synchronizers locked by the corresponding thread. In order to retrieve locked monitor information the lockedMonitors argument should be set to true; in order to retrieve locked synchronizers information lockedSynchronizers should be set to true. For a given ThreadInfo element of the return array the optional information may be inspected by calling ThreadInfo.getLockedMonitors() and ThreadInfo.getLockedSynchronizers() respectively.

      Both lockedMonitors and lockedSynchronizers arguments should only be set to true if the virtual machine supports the requested monitoring.

      Parameters:
      ids - an array of thread identifiers. Each one must be a positive number greater than zero.
      lockedMonitors - boolean indication of whether or not each returned ThreadInfo should hold information on locked object monitors
      lockedSynchronizers - boolean indication of whether or not each returned ThreadInfo should hold information on locked synchronizers
      maxDepth - limits the number of stack frames returned
      Returns:
      an array of ThreadInfo objects with each entry corresponding to one of the threads specified in the input array of identifiers. The return array will therefore have an identical number of elements to the input ids array. If an entry in the ids array is invalid (there is no living thread with the supplied identifier in the virtual machine) then the corresponding entry in the return array will be a null.
      Throws:
      IllegalArgumentException - if any of the entries in the ids array is <=0.
      SecurityException - if there is a security manager in effect and the caller does not have ManagementPermission of "monitor".
      UnsupportedOperationException - if either of the following conditions apply:
      Since:
      10