- All Superinterfaces:
PlatformManagedObject
- All Known Subinterfaces:
ThreadMXBean
Precisely one instance of this interface will be made available to management clients.
Accessing this MXBean
can be done in one of three ways.
- Invoking the static
ManagementFactory.getThreadMXBean()
method. - Using a javax.management.MBeanServerConnection.
- 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 TypeMethodDescriptiondumpAllThreads
(boolean lockedMonitors, boolean lockedSynchronizers) Returns an array ofThreadInfo
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 ofThreadInfo
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 thelong
id of all threads currently waiting on object monitors or ownable synchronizers (synchronizers that make use of theAbstractOwnableSynchronizer
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
getThreadCpuTime
(long id) If supported by the virtual machine, returns the total CPU usage time for the thread with the specified identifier.getThreadInfo
(long id) Returns aThreadInfo
object for the thread with the specified identifier.getThreadInfo
(long[] ids) Returns an array ofThreadInfo
objects ; one for each of the threads specified in the input array of identifiers.getThreadInfo
(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers) Returns an array ofThreadInfo
objects; one for each of the threads specified in theids
argument.default ThreadInfo[]
getThreadInfo
(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth) Returns an array ofThreadInfo
objects; one for each of the threads specified in theids
argument.getThreadInfo
(long[] ids, int maxDepth) Returns an array ofThreadInfo
objects ; one for each of the threads specified in theids
argument.getThreadInfo
(long id, int maxDepth) Returns aThreadInfo
object for the thread with the specified identifier.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.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 theAbstractOwnableSynchronizer
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
setThreadContentionMonitoringEnabled
(boolean enable) 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 thefindDeadlockedThreads()
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 haveManagementPermission
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 methodisThreadCpuTimeEnabled()
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 argumentThread.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 methodisThreadCpuTimeEnabled()
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 argumentThread.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 methodisThreadCpuTimeEnabled()
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 identifierid
present in the virtual machine, a value of-1
is returned. - Throws:
IllegalArgumentException
- ifid
is <=0.UnsupportedOperationException
- if the virtual machine does not support thread CPU timing.- See Also:
-
getThreadInfo
Returns aThreadInfo
object for the thread with the specified identifier. The returned object will not have a stack trace so that a call to itsgetStackTrace()
method will result in an emptyStackTraceElement
array. Similarly, the returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls togetLockedMonitors()
andgetLockedSynchronizers
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 aThreadInfo
object corresponding to that thread. Otherwise, returnsnull
. - Throws:
IllegalArgumentException
- ifid
is <=0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
of "monitor".
-
getThreadInfo
Returns an array ofThreadInfo
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 itsgetStackTrace()
method will result in an emptyStackTraceElement
array. Similarly, the returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls togetLockedMonitors()
andgetLockedSynchronizers
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 inputids
array. If an entry in theids
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 anull
. - Throws:
IllegalArgumentException
- if any of the entries in theids
array is <=0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
of "monitor".
-
getThreadInfo
Returns an array ofThreadInfo
objects ; one for each of the threads specified in theids
argument. The stack trace information in the returned objects will depend on the value of themaxDepth
argument which specifies the maximum number ofStackTraceElement
instances to try and include. A subsequent call to any of the returned objects'getStackTrace()
method should result in aStackTraceElement
array of up tomaxDepth
elements. AmaxDepth
value ofInteger.MAX_VALUE
will attempt to obtain all of the stack trace information for each specified thread while amaxDepth
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()
andgetLockedSynchronizers
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 returnedThreadInfo
objects. SupplyingInteger.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 theids
argument. Null elements will be placed in the array if the corresponding thread identifier inids
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 inids
is <=0.IllegalArgumentException
- ifmaxDepth
is <0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
of "monitor".
-
getThreadInfo
Returns an array ofThreadInfo
objects; one for each of the threads specified in theids
argument. EachThreadInfo
will hold details of all of the stack trace information for each specified thread. The returnedThreadInfo
objects will optionally contain details of all monitor objects and synchronizers locked by the corresponding thread. In order to retrieve locked monitor information thelockedMonitors
argument should be set totrue
; in order to retrieve locked synchronizers informationlockedSynchronizers
should be set totrue
. For a givenThreadInfo
element of the return array the optional information may be inspected by callingThreadInfo.getLockedMonitors()
andThreadInfo.getLockedSynchronizers()
respectively.Both
lockedMonitors
andlockedSynchronizers
arguments should only be set totrue
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 returnedThreadInfo
should hold information on locked object monitorslockedSynchronizers
- boolean indication of whether or not each returnedThreadInfo
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 inputids
array. If an entry in theids
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 anull
. - Throws:
IllegalArgumentException
- if any of the entries in theids
array is <=0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
of "monitor".UnsupportedOperationException
- if either of the following conditions apply:lockedMonitors
istrue
but a call toisObjectMonitorUsageSupported()
would result in afalse
valuelockedSynchronizers
istrue
but a call toisSynchronizerUsageSupported()
would result in afalse
value
-
getThreadInfo
Returns aThreadInfo
object for the thread with the specified identifier. The stack trace information in the returned object will depend on the value of themaxDepth
argument which specifies the maximum number ofStackTraceElement
instances to include. A subsequent call to the returned object'sgetStackTrace()
method should then result in aStackTraceElement
array of up tomaxDepth
elements. AmaxDepth
value ofInteger.MAX_VALUE
will obtain all of the stack trace information for the thread while amaxDepth
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 ofStackTraceElement
s.The returned object will hold no details of locked synchronizers or locked object monitors for the specified thread; calls to
getLockedMonitors()
andgetLockedSynchronizers
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 returnedThreadInfo
object. SupplyingInteger.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 aThreadInfo
object corresponding to that thread. Otherwise, returnsnull
. - Throws:
IllegalArgumentException
- ifid
is <=0.IllegalArgumentException
- ifmaxDepth
is <0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
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 methodisThreadCpuTimeEnabled()
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 identifierid
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
- ifid
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
ifisThreadCpuTimeSupported()
returnstrue
.- Returns:
true
if CPU timing of the current thread is supported, otherwisefalse
.
-
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 haveManagementPermission
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 iftrue
, otherwise disable thread contention monitoring.- Throws:
SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
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 iftrue
, otherwise disable thread CPU timing- Throws:
SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
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, otherwisefalse
- 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 theAbstractOwnableSynchronizer
type and which are completely owned by a single thread).- Returns:
true
if synchronizer usage monitoring is permitted, otherwisefalse
-
findDeadlockedThreads
long[] findDeadlockedThreads()If supported by the virtual machine, this method can be used to retrieve thelong
id of all threads currently waiting on object monitors or ownable synchronizers (synchronizers that make use of theAbstractOwnableSynchronizer
type and which are completely owned by a single thread). To determine the threads currently deadlocked by object monitors only use thefindMonitorDeadlockedThreads()
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 haveManagementPermission
of "monitor".UnsupportedOperationException
- if the virtual machine does not support any monitoring of ownable synchronizers.- See Also:
-
dumpAllThreads
Returns an array ofThreadInfo
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 arraylockedSynchronizers
- 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 haveManagementPermission
of "monitor".UnsupportedOperationException
- if either of the following conditions apply:lockedMonitors
istrue
but a call toisObjectMonitorUsageSupported()
would result in afalse
valuelockedSynchronizers
istrue
but a call toisSynchronizerUsageSupported()
would result in afalse
value
-
dumpAllThreads
default ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth) Returns an array ofThreadInfo
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 arraylockedSynchronizers
- boolean indication of whether or not information on all currently locked ownable synchronizers is to be included in the returned arraymaxDepth
- 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 haveManagementPermission
of "monitor".UnsupportedOperationException
- if either of the following conditions apply:lockedMonitors
istrue
but a call toisObjectMonitorUsageSupported()
would result in afalse
valuelockedSynchronizers
istrue
but a call toisSynchronizerUsageSupported()
would result in afalse
value
- Since:
- 10
-
getThreadInfo
default ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers, int maxDepth) Returns an array ofThreadInfo
objects; one for each of the threads specified in theids
argument. EachThreadInfo
will hold details of all of the stack trace information for each specified thread. The returnedThreadInfo
objects will optionally contain details of all monitor objects and synchronizers locked by the corresponding thread. In order to retrieve locked monitor information thelockedMonitors
argument should be set totrue
; in order to retrieve locked synchronizers informationlockedSynchronizers
should be set totrue
. For a givenThreadInfo
element of the return array the optional information may be inspected by callingThreadInfo.getLockedMonitors()
andThreadInfo.getLockedSynchronizers()
respectively.Both
lockedMonitors
andlockedSynchronizers
arguments should only be set totrue
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 returnedThreadInfo
should hold information on locked object monitorslockedSynchronizers
- boolean indication of whether or not each returnedThreadInfo
should hold information on locked synchronizersmaxDepth
- 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 inputids
array. If an entry in theids
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 anull
. - Throws:
IllegalArgumentException
- if any of the entries in theids
array is <=0.SecurityException
- if there is a security manager in effect and the caller does not haveManagementPermission
of "monitor".UnsupportedOperationException
- if either of the following conditions apply:lockedMonitors
istrue
but a call toisObjectMonitorUsageSupported()
would result in afalse
valuelockedSynchronizers
istrue
but a call toisSynchronizerUsageSupported()
would result in afalse
value
- Since:
- 10
-