java.lang.management
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.
Modifier and Type | Method and Description |
---|---|
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.
|
ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers)
getThreadInfo(long[], boolean,
boolean)
with the return value of getAllThreadIds()
.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.ThreadInfo
objects for all live threads.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.getThreadInfo(long[], boolean, boolean)
,
getAllThreadIds()
,
isObjectMonitorUsageSupported()
,
isSynchronizerUsageSupported()
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.
null
if there are no deadlocks.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").UnsupportedOperationException
- if the VM does not support
the monitoring of ownable
synchronizer usage.findMonitorDeadlockedThreads()
,
isSynchronizerUsageSupported()
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.
null
if there are no deadlocks.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").findDeadlockedThreads()
long[] getAllThreadIds()
SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").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.
UnsupportedOperationException
- if CPU time monitoring is not
supported.getCurrentThreadUserTime()
,
isCurrentThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
setThreadCpuTimeEnabled(boolean)
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.
UnsupportedOperationException
- if CPU time monitoring is not
supported.getCurrentThreadCpuTime()
,
isCurrentThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
setThreadCpuTimeEnabled(boolean)
int getDaemonThreadCount()
int getPeakThreadCount()
resetPeakThreadCount()
.resetPeakThreadCount()
int getThreadCount()
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.
id
- the thread identifier of the thread whose CPU time is being
monitored.IllegalArgumentException
- if id
<= 0.UnsupportedOperationException
- if CPU time monitoring is not
supported.getThreadUserTime(long)
,
isThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
setThreadCpuTimeEnabled(boolean)
ThreadInfo getThreadInfo(long id)
getThreadInfo(long)
(id, 0)
. If the
identifier specifies a thread which is either non-existant
or not alive, then the method returns null
.id
- the identifier of the thread to return information
on.ThreadInfo
object pertaining to the specified
thread, or null
if the identifier specifies
a thread that doesn't exist or is not alive.IllegalArgumentException
- if id
<= 0.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").ThreadInfo[] getThreadInfo(long[] ids)
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
.ids
- an array of thread identifiers to return information
on.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.IllegalArgumentException
- if an identifier in the array is
<= 0.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers)
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
.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.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.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.isObjectMonitorUsageSupported()
,
isSynchronizerUsageSupported()
ThreadInfo getThreadInfo(long id, int maxDepth)
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.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.ThreadInfo
object pertaining to the specified
thread, or null
if the identifier specifies
a thread that doesn't exist or is not alive.IllegalArgumentException
- if id
<= 0.IllegalArgumentException
- if maxDepth
< 0.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").ThreadInfo[] getThreadInfo(long[] ids, int maxDepth)
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.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.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.IllegalArgumentException
- if an identifier in the array is
<= 0.IllegalArgumentException
- if maxDepth
< 0.SecurityException
- if a security manager exists and
denies ManagementPermission("monitor").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.
id
- the thread identifier of the thread whose CPU time is being
monitored.IllegalArgumentException
- if id
<= 0.UnsupportedOperationException
- if CPU time monitoring is not
supported.getThreadCpuTime(long)
,
isThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
setThreadCpuTimeEnabled(boolean)
long getTotalStartedThreadCount()
boolean isCurrentThreadCpuTimeSupported()
isThreadCpuTimeSupported()
returning true.isThreadCpuTimeEnabled()
,
isThreadCpuTimeSupported()
,
setThreadCpuTimeEnabled(boolean)
boolean isObjectMonitorUsageSupported()
boolean isSynchronizerUsageSupported()
boolean isThreadContentionMonitoringEnabled()
UnsupportedOperationException
- if the virtual
machine does not
support contention
monitoring.isThreadContentionMonitoringSupported()
,
setThreadContentionMonitoringEnabled(boolean)
boolean isThreadContentionMonitoringSupported()
isThreadContentionMonitoringEnabled()
,
setThreadContentionMonitoringEnabled(boolean)
boolean isThreadCpuTimeEnabled()
UnsupportedOperationException
- if the virtual
machine does not
support CPU time
monitoring.isCurrentThreadCpuTimeSupported()
,
isThreadCpuTimeSupported()
,
setThreadCpuTimeEnabled(boolean)
boolean isThreadCpuTimeSupported()
isCurrentThreadCpuTimeSupported()
returns true.isCurrentThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
setThreadCpuTimeEnabled(boolean)
void resetPeakThreadCount()
getThreadCount()
.SecurityException
- if a security manager exists and
denies ManagementPermission("control").getPeakThreadCount()
,
getThreadCount()
void setThreadContentionMonitoringEnabled(boolean enable)
enable
- true if monitoring should be enabled,
false if it should be disabled.UnsupportedOperationException
- if the virtual
machine does not
support contention
monitoring.SecurityException
- if a security manager exists and
denies ManagementPermission("control").isThreadContentionMonitoringEnabled()
,
isThreadContentionMonitoringSupported()
void setThreadCpuTimeEnabled(boolean enable)
enable
- true if monitoring should be enabled,
false if it should be disabled.UnsupportedOperationException
- if the virtual
machine does not
support CPU time
monitoring.SecurityException
- if a security manager exists and
denies ManagementPermission("control").isCurrentThreadCpuTimeSupported()
,
isThreadCpuTimeEnabled()
,
isThreadCpuTimeSupported()