java.lang.management
Interface ThreadMXBean


public interface ThreadMXBean

Provides access to information about the threads of the virtual machine. An instance of this bean is obtained by calling ManagementFactory.getThreadMXBean().

Each thread within the virtual machine is given an identifier, which is guaranteed to be unique to a particular thread over its lifetime (after which it may be reused). The identifier for a thread may be obtained by calling Thread.getId(). This identifier is used within implementations of this interface to obtain information about a particular thread (or series of threads, in the case of an array of identifiers).

This bean supports some optional behaviour, which all virtual machines may not choose to implement. Specifically, this includes the monitoring of:

The monitoring of CPU time is further subdivided into the monitoring of either just the current thread or all threads. The methods isThreadCpuTimeSupported(), isCurrentThreadCpuTimeSupported() isThreadContentionMonitoringSupported(), isObjectMonitorUsageSupported() and isSynchronizerUsageSupported() may be used to determine whether or not this functionality is supported.

Furthermore, both time and contention monitoring may be disabled. In fact, thread contention monitoring is disabled by default, and must be explictly turned on by calling the setThreadContentionMonitoringEnabled(boolean) method.

Since:
1.5

Method Summary
 ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers)
          This method returns information on all live threads at the time of execution (some threads may have terminated by the time the method completes).
 long[] findDeadlockedThreads()
           This method obtains a list of threads which are deadlocked waiting to obtain monitor or ownable synchronizer ownership.
 long[] findMonitorDeadlockedThreads()
           This method obtains a list of threads which are deadlocked waiting to obtain monitor ownership.
 long[] getAllThreadIds()
          Returns all live thread identifiers at the time of initial execution.
 long getCurrentThreadCpuTime()
           Returns the total number of nanoseconds of CPU time the current thread has used.
 long getCurrentThreadUserTime()
           Returns the total number of nanoseconds of CPU time the current thread has executed in user mode.
 int getDaemonThreadCount()
          Returns the number of live daemon threads.
 int getPeakThreadCount()
          Returns the peak number of live threads since the virtual machine was started or the count reset using resetPeakThreadCount().
 int getThreadCount()
          Returns the number of live threads, including both daemon threads and non-daemon threads.
 long getThreadCpuTime(long id)
           Returns the total number of nanoseconds of CPU time the specified thread has used.
 ThreadInfo getThreadInfo(long id)
          Returns information on the specified thread without any stack trace information.
 ThreadInfo[] getThreadInfo(long[] ids)
          Returns information on the specified threads without any stack trace information.
 ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers)
          Returns information on the specified threads with full stack trace information and optional synchronization information.
 ThreadInfo[] getThreadInfo(long[] ids, int maxDepth)
          Returns information on the specified threads with stack trace information to the supplied depth.
 ThreadInfo getThreadInfo(long id, int maxDepth)
          Returns information on the specified thread with stack trace information to the supplied depth.
 long getThreadUserTime(long id)
           Returns the total number of nanoseconds of CPU time the specified thread has executed in user mode.
 long getTotalStartedThreadCount()
          Returns the total number of threads that have been created and started during the lifetime of the virtual machine.
 boolean isCurrentThreadCpuTimeSupported()
          Returns true if the virtual machine supports the monitoring of the CPU time used by the current thread.
 boolean isObjectMonitorUsageSupported()
          Returns true if the virtual machine supports the monitoring of object monitor usage.
 boolean isSynchronizerUsageSupported()
          Returns true if the virtual machine supports the monitoring of ownable synchronizer usage.
 boolean isThreadContentionMonitoringEnabled()
          Returns true if thread contention monitoring is currently enabled.
 boolean isThreadContentionMonitoringSupported()
          Returns true if thread contention monitoring is supported by the virtual machine.
 boolean isThreadCpuTimeEnabled()
          Returns true if monitoring of the CPU time used by a thread is currently enabled.
 boolean isThreadCpuTimeSupported()
          Returns true if the virtual machine supports the monitoring of the CPU time used by all threads.
 void resetPeakThreadCount()
          Resets the peak live thread count to the current number of live threads, as returned by getThreadCount().
 void setThreadContentionMonitoringEnabled(boolean enable)
          Toggles the monitoring of thread contention.
 void setThreadCpuTimeEnabled(boolean enable)
          Toggles the monitoring of CPU time used by threads.
 

Method Detail

dumpAllThreads

ThreadInfo[] dumpAllThreads(boolean lockedMonitors,
                            boolean lockedSynchronizers)
This method returns information on all live threads at the time of execution (some threads may have terminated by the time the method completes). This method is simply a shorthand for calling getThreadInfo(long[], boolean, boolean) with the return value of getAllThreadIds().

Parameters:
lockedMonitors - true if the returned ThreadInfo objects should contain information on locked monitors.
lockedSynchronizers - true if the returned ThreadInfo objects should contain information on locked ownable synchronizers.
Returns:
an array of ThreadInfo objects for all live threads.
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("monitor").
UnsupportedOperationException - if lockedMonitors is true, but object monitor usage monitoring is not supported by the VM, or lockedSynchronizers is true, but ownable synchronizer usage monitoring is not supported by the VM.
Since:
1.6
See Also:
getThreadInfo(long[], boolean, boolean), getAllThreadIds(), isObjectMonitorUsageSupported(), isSynchronizerUsageSupported()

findDeadlockedThreads

long[] findDeadlockedThreads()

This method obtains a list of threads which are deadlocked waiting to obtain monitor or ownable synchronizer ownership. This is similar to the behaviour described for #getMonitorDeadlockedThreads(), except this method also takes in to account deadlocks involving ownable synchronizers.

Note that this method is not designed for controlling synchronization, but for troubleshooting problems which cause such deadlocks; it may be prohibitively expensive to use in normal operation. If only deadlocks involving monitors are of interest, then findMonitorDeadlockedThreads() should be used in preference to this method.

Returns:
an array of thread identifiers, corresponding to threads which are currently in a deadlocked situation, or null if there are no deadlocks.
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("monitor").
UnsupportedOperationException - if the VM does not support the monitoring of ownable synchronizer usage.
Since:
1.6
See Also:
findMonitorDeadlockedThreads(), isSynchronizerUsageSupported()

findMonitorDeadlockedThreads

long[] findMonitorDeadlockedThreads()

This method obtains a list of threads which are deadlocked waiting to obtain monitor ownership. On entering a synchronized method of an object, or re-entering it after returning from an Object.wait() call, a thread obtains ownership of the object's monitor.

Deadlocks can occur in this situation if one or more threads end up waiting for a monitor, P, while also retaining ownership of a monitor, Q, required by the thread that currently owns P. To give a simple example, imagine thread A calls a synchronized method, R, obtaining the monitor, P. It then sleeps within that method, allowing thread B to run, but still retaining ownership of P. B calls another synchronized method, S, which causes it to obtain the monitor, Q, of a different object. While in that method, it then wants to call the original synchronized method, R, called by A. Doing so requires ownership of P, which is still held by A. Hence, it becomes blocked.

A then finishes its sleep, becomes runnable, and is then allowed to run, being the only eligible thread in this scenario. A tries to call the synchronized method, S. It also gets blocked, because B still holds the monitor, Q. Hence, the two threads, A and B, are deadlocked, as neither can give up its monitor without first obtaining the monitor held by the other thread.

Calling this method in this scenario would return the thread IDs of A and B. Note that this method is not designed for controlling synchronization, but for troubleshooting problems which cause such deadlocks; it may be prohibitively expensive to use in normal operation. This method only returns deadlocks involving monitors; to include deadlocks involving ownable synchronizers, findDeadlockedThreads() should be used instead.

Returns:
an array of thread identifiers, corresponding to threads which are currently in a deadlocked situation, or null if there are no deadlocks.
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("monitor").
See Also:
findDeadlockedThreads()

getAllThreadIds

long[] getAllThreadIds()
Returns all live thread identifiers at the time of initial execution. Some thread identifiers in the returned array may refer to terminated threads, if this occurs during the lifetime of this method.

Returns:
an array of thread identifiers, corresponding to current live threads.
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getCurrentThreadCpuTime

long getCurrentThreadCpuTime()

Returns the total number of nanoseconds of CPU time the current thread has used. This is equivalent to calling #getThreadCpuTime()(Thread.currentThread.getId()).

Note that the value is only nanosecond-precise, and not accurate; there is no guarantee that the difference between two values is really a nanosecond. Also, the value is prone to overflow if the offset exceeds 2^63. The use of this method depends on virtual machine support for measurement of the CPU time of the current thread, and on this functionality being enabled.

Returns:
the total number of nanoseconds of CPU time the current thread has used, or -1 if CPU time monitoring is disabled.
Throws:
UnsupportedOperationException - if CPU time monitoring is not supported.
See Also:
getCurrentThreadUserTime(), isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getCurrentThreadUserTime

long getCurrentThreadUserTime()

Returns the total number of nanoseconds of CPU time the current thread has executed in user mode. This is equivalent to calling #getThreadUserTime()(Thread.currentThread.getId()).

Note that the value is only nanosecond-precise, and not accurate; there is no guarantee that the difference between two values is really a nanosecond. Also, the value is prone to overflow if the offset exceeds 2^63. The use of this method depends on virtual machine support for measurement of the CPU time of the current thread, and on this functionality being enabled.

Returns:
the total number of nanoseconds of CPU time the current thread has executed in user mode, or -1 if CPU time monitoring is disabled.
Throws:
UnsupportedOperationException - if CPU time monitoring is not supported.
See Also:
getCurrentThreadCpuTime(), isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getDaemonThreadCount

int getDaemonThreadCount()
Returns the number of live daemon threads.

Returns:
the number of live daemon threads.

getPeakThreadCount

int getPeakThreadCount()
Returns the peak number of live threads since the virtual machine was started or the count reset using resetPeakThreadCount().

Returns:
the peak live thread count.
See Also:
resetPeakThreadCount()

getThreadCount

int getThreadCount()
Returns the number of live threads, including both daemon threads and non-daemon threads.

Returns:
the current number of live threads.

getThreadCpuTime

long getThreadCpuTime(long id)

Returns the total number of nanoseconds of CPU time the specified thread has used.

Note that the value is only nanosecond-precise, and not accurate; there is no guarantee that the difference between two values is really a nanosecond. Also, the value is prone to overflow if the offset exceeds 2^63. The use of this method depends on virtual machine support for measurement of the CPU time of the current thread, and on this functionality being enabled.

Parameters:
id - the thread identifier of the thread whose CPU time is being monitored.
Returns:
the total number of nanoseconds of CPU time the specified thread has used, or -1 if CPU time monitoring is disabled.
Throws:
IllegalArgumentException - if id <= 0.
UnsupportedOperationException - if CPU time monitoring is not supported.
See Also:
getThreadUserTime(long), isThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getThreadInfo

ThreadInfo getThreadInfo(long id)
Returns information on the specified thread without any stack trace information. This is equivalent to getThreadInfo(long)(id, 0). If the identifier specifies a thread which is either non-existant or not alive, then the method returns null.

Parameters:
id - the identifier of the thread to return information on.
Returns:
a ThreadInfo object pertaining to the specified thread, or null if the identifier specifies a thread that doesn't exist or is not alive.
Throws:
IllegalArgumentException - if id <= 0.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadInfo

ThreadInfo[] getThreadInfo(long[] ids)
Returns information on the specified threads without any stack trace information. This is equivalent to getThreadInfo(long)(ids, 0). If an identifier specifies a thread which is either non-existant or not alive, then the corresponding element in the returned array is null.

Parameters:
ids - an array of thread identifiers to return information on.
Returns:
an array of ThreadInfo objects matching the specified threads. The corresponding element is null if the identifier specifies a thread that doesn't exist or is not alive.
Throws:
IllegalArgumentException - if an identifier in the array is <= 0.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadInfo

ThreadInfo[] getThreadInfo(long[] ids,
                           boolean lockedMonitors,
                           boolean lockedSynchronizers)
Returns information on the specified threads with full stack trace information and optional synchronization information. If lockedMonitors is false, or there are no locked monitors for a particular thread, then the corresponding ThreadInfo object will have an empty MonitorInfo array. Likewise, if lockedSynchronizers is false, or there are no locked ownable synchronizers for a particular thread, then the corresponding ThreadInfo object will have an empty LockInfo array. If both lockedMonitors and lockedSynchronizers are false, the return value is equivalent to that from getThreadInfo(long)(ids, Integer.MAX_VALUE). If an identifier specifies a thread which is either non-existant or not alive, then the corresponding element in the returned array is null.

Parameters:
ids - an array of thread identifiers to return information on.
lockedMonitors - true if information on locked monitors should be included.
lockedSynchronizers - true if information on locked ownable synchronizers should be included.
Returns:
an array of ThreadInfo objects matching the specified threads. The corresponding element is null if the identifier specifies a thread that doesn't exist or is not alive.
Throws:
IllegalArgumentException - if an identifier in the array is <= 0.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").
UnsupportedOperationException - if lockedMonitors is true, but object monitor usage monitoring is not supported by the VM, or lockedSynchronizers is true, but ownable synchronizer usage monitoring is not supported by the VM.
Since:
1.6
See Also:
isObjectMonitorUsageSupported(), isSynchronizerUsageSupported()

getThreadInfo

ThreadInfo getThreadInfo(long id,
                         int maxDepth)
Returns information on the specified thread with stack trace information to the supplied depth. If the identifier specifies a thread which is either non-existant or not alive, then the method returns null. A maximum depth of 0 corresponds to an empty stack trace (an empty array is returned by the appropriate ThreadInfo method). A maximum depth of Integer.MAX_VALUE returns the full stack trace.

Parameters:
id - the identifier of the thread to return information on.
maxDepth - the maximum depth of the stack trace. Values of 0 or Integer.MAX_VALUE correspond to an empty and full stack trace respectively.
Returns:
a ThreadInfo object pertaining to the specified thread, or null if the identifier specifies a thread that doesn't exist or is not alive.
Throws:
IllegalArgumentException - if id <= 0.
IllegalArgumentException - if maxDepth < 0.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadInfo

ThreadInfo[] getThreadInfo(long[] ids,
                           int maxDepth)
Returns information on the specified threads with stack trace information to the supplied depth. If an identifier specifies a thread which is either non-existant or not alive, then the corresponding element in the returned array is null. A maximum depth of 0 corresponds to an empty stack trace (an empty array is returned by the appropriate ThreadInfo method). A maximum depth of Integer.MAX_VALUE returns the full stack trace.

Parameters:
ids - an array of thread identifiers to return information on.
maxDepth - the maximum depth of the stack trace. Values of 0 or Integer.MAX_VALUE correspond to an empty and full stack trace respectively.
Returns:
an array of ThreadInfo objects matching the specified threads. The corresponding element is null if the identifier specifies a thread that doesn't exist or is not alive.
Throws:
IllegalArgumentException - if an identifier in the array is <= 0.
IllegalArgumentException - if maxDepth < 0.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadUserTime

long getThreadUserTime(long id)

Returns the total number of nanoseconds of CPU time the specified thread has executed in user mode.

Note that the value is only nanosecond-precise, and not accurate; there is no guarantee that the difference between two values is really a nanosecond. Also, the value is prone to overflow if the offset exceeds 2^63. The use of this method depends on virtual machine support for measurement of the CPU time of the current thread, and on this functionality being enabled.

Parameters:
id - the thread identifier of the thread whose CPU time is being monitored.
Returns:
the total number of nanoseconds of CPU time the specified thread has executed in user mode, or -1 if CPU time monitoring is disabled.
Throws:
IllegalArgumentException - if id <= 0.
UnsupportedOperationException - if CPU time monitoring is not supported.
See Also:
getThreadCpuTime(long), isThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

getTotalStartedThreadCount

long getTotalStartedThreadCount()
Returns the total number of threads that have been created and started during the lifetime of the virtual machine.

Returns:
the total number of started threads.

isCurrentThreadCpuTimeSupported

boolean isCurrentThreadCpuTimeSupported()
Returns true if the virtual machine supports the monitoring of the CPU time used by the current thread. This is implied by isThreadCpuTimeSupported() returning true.

Returns:
true if monitoring of the CPU time used by the current thread is supported by the virtual machine.
See Also:
isThreadCpuTimeEnabled(), isThreadCpuTimeSupported(), setThreadCpuTimeEnabled(boolean)

isObjectMonitorUsageSupported

boolean isObjectMonitorUsageSupported()
Returns true if the virtual machine supports the monitoring of object monitor usage.

Returns:
true if the monitoring of object monitor usage is supported by the virtual machine.
Since:
1.6

isSynchronizerUsageSupported

boolean isSynchronizerUsageSupported()
Returns true if the virtual machine supports the monitoring of ownable synchronizer usage.

Returns:
true if the monitoring of ownable synchronizer usage is supported by the virtual machine.
Since:
1.6

isThreadContentionMonitoringEnabled

boolean isThreadContentionMonitoringEnabled()
Returns true if thread contention monitoring is currently enabled.

Returns:
true if thread contention monitoring is enabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support contention monitoring.
See Also:
isThreadContentionMonitoringSupported(), setThreadContentionMonitoringEnabled(boolean)

isThreadContentionMonitoringSupported

boolean isThreadContentionMonitoringSupported()
Returns true if thread contention monitoring is supported by the virtual machine.

Returns:
true if thread contention monitoring is supported by the virtual machine.
See Also:
isThreadContentionMonitoringEnabled(), setThreadContentionMonitoringEnabled(boolean)

isThreadCpuTimeEnabled

boolean isThreadCpuTimeEnabled()
Returns true if monitoring of the CPU time used by a thread is currently enabled.

Returns:
true if thread CPU time monitoring is enabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support CPU time monitoring.
See Also:
isCurrentThreadCpuTimeSupported(), isThreadCpuTimeSupported(), setThreadCpuTimeEnabled(boolean)

isThreadCpuTimeSupported

boolean isThreadCpuTimeSupported()
Returns true if the virtual machine supports the monitoring of the CPU time used by all threads. This implies that isCurrentThreadCpuTimeSupported() returns true.

Returns:
true if monitoring of the CPU time used by the current thread is supported by the virtual machine.
See Also:
isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), setThreadCpuTimeEnabled(boolean)

resetPeakThreadCount

void resetPeakThreadCount()
Resets the peak live thread count to the current number of live threads, as returned by getThreadCount().

Throws:
SecurityException - if a security manager exists and denies ManagementPermission("control").
See Also:
getPeakThreadCount(), getThreadCount()

setThreadContentionMonitoringEnabled

void setThreadContentionMonitoringEnabled(boolean enable)
Toggles the monitoring of thread contention. Thread contention monitoring is disabled by default. Each time contention monitoring is re-enabled, the times it maintains are reset.

Parameters:
enable - true if monitoring should be enabled, false if it should be disabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support contention monitoring.
SecurityException - if a security manager exists and denies ManagementPermission("control").
See Also:
isThreadContentionMonitoringEnabled(), isThreadContentionMonitoringSupported()

setThreadCpuTimeEnabled

void setThreadCpuTimeEnabled(boolean enable)
Toggles the monitoring of CPU time used by threads. The initial setting is dependent on the underlying virtual machine. On enabling CPU time monitoring, the virtual machine may take any value up to and including the current time as the start time for monitoring.

Parameters:
enable - true if monitoring should be enabled, false if it should be disabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support CPU time monitoring.
SecurityException - if a security manager exists and denies ManagementPermission("control").
See Also:
isCurrentThreadCpuTimeSupported(), isThreadCpuTimeEnabled(), isThreadCpuTimeSupported()