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 {@link 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 {@link java.lang.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 CPU time used by a thread, and the monitoring of thread contention. The former is further subdivided into the monitoring of either just the current thread or all threads. The methods {@link #isThreadCpuTimeSupported()}, {@link #isCurrentThreadCpuTimeSupported()} and {@link #isThreadContentionMonitoringSupported()} may be used to determine whether or not this functionality is supported.
Furthermore, both these facilities may be disabled. In fact, thread contention monitoring is disabled by default, and must be explictly turned on by calling the {@link #setThreadContentionMonitoringEnabled(boolean)} method.
Since: 1.5
Method Summary | |
---|---|
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 {@link #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 id, int maxDepth)
Returns information on the specified thread with
stack trace information to the supplied depth. |
ThreadInfo[] | getThreadInfo(long[] ids, int maxDepth)
Returns information on the specified threads 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 | 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 {@link #getThreadCount()}.
|
void | setThreadContentionMonitoringEnabled(boolean enable)
Toggles the monitoring of thread contention. |
void | setThreadCpuTimeEnabled(boolean enable)
Toggles the monitoring of CPU time used by threads. |
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 {@link java.lang.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.
Returns: an array of thread identifiers, corresponding to threads which are currently in a deadlocked situation.
Throws: SecurityException if a security manager exists and denies ManagementPermission("monitor").
Returns: an array of thread identifiers, corresponding to current live threads.
Throws: SecurityException if a security manager exists and denies ManagementPermission("monitor").
Returns the total number of nanoseconds of CPU time
the current thread has used. This is equivalent to calling
{@link #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 ThreadMXBean
Returns the total number of nanoseconds of CPU time
the current thread has executed in user mode. This is
equivalent to calling
{@link #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 ThreadMXBean
Returns: the number of live daemon threads.
Returns: the peak live thread count.
See Also: resetPeakThreadCount
Returns: the current number of live threads.
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: ThreadMXBean isThreadCpuTimeSupported isThreadCpuTimeEnabled ThreadMXBean
{@link #getThreadInfo}(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 {@link 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").
{@link #getThreadInfo}(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 {@link 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").
null
.
A maximum depth of 0 corresponds to an empty stack trace
(an empty array is returned by the appropriate
{@link 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 {@link 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").
null
. A maximum depth of 0 corresponds
to an empty stack trace (an empty array is returned by the
appropriate {@link 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 {@link 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").
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: ThreadMXBean isThreadCpuTimeSupported isThreadCpuTimeEnabled ThreadMXBean
Returns: the total number of started threads.
Returns: true if monitoring of the CPU time used by the current thread is supported by the virtual machine.
See Also: isThreadCpuTimeEnabled isThreadCpuTimeSupported ThreadMXBean
Returns: true if thread contention monitoring is enabled.
Throws: UnsupportedOperationException if the virtual machine does not support contention monitoring.
See Also: isThreadContentionMonitoringSupported ThreadMXBean
Returns: true if thread contention monitoring is supported by the virtual machine.
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 ThreadMXBean
Returns: true if monitoring of the CPU time used by the current thread is supported by the virtual machine.
See Also: isCurrentThreadCpuTimeSupported isThreadCpuTimeEnabled ThreadMXBean
Throws: SecurityException if a security manager exists and denies ManagementPermission("control").
See Also: getPeakThreadCount getThreadCount
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
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