gnu.java.lang.management

Class ThreadMXBeanImpl

Implemented Interfaces:
DynamicMBean, ThreadMXBean

public final class ThreadMXBeanImpl
extends BeanImpl
implements ThreadMXBean

Provides access to information about the threads of the virtual machine. An instance of this bean is obtained by calling ManagementFactory.getThreadMXBean(). See ThreadMXBean for full documentation.
Since:
1.5

Constructor Summary

ThreadMXBeanImpl()
Default constructor to set up flag states.

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 ThreadMXBean.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 id, int maxDepth)
Returns information on the specified thread with stack trace information to the supplied depth.
ThreadInfo[]
getThreadInfo(long[] ids)
Returns information on the specified threads without any stack trace information.
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 ThreadMXBean.getThreadCount().
void
setThreadContentionMonitoringEnabled(boolean enable)
Toggles the monitoring of thread contention.
void
setThreadCpuTimeEnabled(boolean enable)
Toggles the monitoring of CPU time used by threads.

Methods inherited from class gnu.java.lang.management.BeanImpl

checkControlPermissions, checkMonitorPermissions

Methods inherited from class javax.management.StandardMBean

cacheMBeanInfo, getAttribute, getAttributes, getCachedMBeanInfo, getClassName, getConstructors, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getImpact, getImplementation, getImplementationClass, getMBeanInfo, getMBeanInterface, getParameterName, getParameterName, invoke, setAttribute, setAttributes, setImplementation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ThreadMXBeanImpl

public ThreadMXBeanImpl()
            throws NotCompliantMBeanException
Default constructor to set up flag states. The VM has to specify whether time monitoring is initially enabled or not.
Throws:
NotCompliantMBeanException - if this class doesn't implement the interface or a method appears in the interface that doesn't comply with the naming conventions.

Method Details

findMonitorDeadlockedThreads

public 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.

Specified by:
findMonitorDeadlockedThreads in interface ThreadMXBean
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").

getAllThreadIds

public 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.
Specified by:
getAllThreadIds in interface ThreadMXBean
Returns:
an array of thread identifiers, corresponding to current live threads.
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getCurrentThreadCpuTime

public 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.

Specified by:
getCurrentThreadCpuTime in interface ThreadMXBean
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.

getCurrentThreadUserTime

public 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.

Specified by:
getCurrentThreadUserTime in interface ThreadMXBean
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.

getDaemonThreadCount

public int getDaemonThreadCount()
Returns the number of live daemon threads.
Specified by:
getDaemonThreadCount in interface ThreadMXBean
Returns:
the number of live daemon threads.

getPeakThreadCount

public int getPeakThreadCount()
Returns the peak number of live threads since the virtual machine was started or the count reset using ThreadMXBean.resetPeakThreadCount().
Specified by:
getPeakThreadCount in interface ThreadMXBean
Returns:
the peak live thread count.

getThreadCount

public int getThreadCount()
Returns the number of live threads, including both daemon threads and non-daemon threads.
Specified by:
getThreadCount in interface ThreadMXBean
Returns:
the current number of live threads.

getThreadCpuTime

public 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.

Specified by:
getThreadCpuTime in interface ThreadMXBean
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.

getThreadInfo

public ThreadInfo getThreadInfo(long id)
Returns information on the specified thread without any stack trace information. This is equivalent to getThreadInfo(id, 0). If the identifier specifies a thread which is either non-existant or not alive, then the method returns null.
Specified by:
getThreadInfo in interface ThreadMXBean
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

public 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.
Specified by:
getThreadInfo in interface ThreadMXBean
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 <320.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadInfo

public ThreadInfo[] getThreadInfo(long[] ids)
Returns information on the specified threads without any stack trace information. This is equivalent to 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.
Specified by:
getThreadInfo in interface ThreadMXBean
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

public 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.
Specified by:
getThreadInfo in interface ThreadMXBean
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 <320.
SecurityException - if a security manager exists and denies ManagementPermission("monitor").

getThreadUserTime

public 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.

Specified by:
getThreadUserTime in interface ThreadMXBean
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.

getTotalStartedThreadCount

public long getTotalStartedThreadCount()
Returns the total number of threads that have been created and started during the lifetime of the virtual machine.
Specified by:
getTotalStartedThreadCount in interface ThreadMXBean
Returns:
the total number of started threads.

isCurrentThreadCpuTimeSupported

public 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.
Specified by:
isCurrentThreadCpuTimeSupported in interface ThreadMXBean
Returns:
true if monitoring of the CPU time used by the current thread is supported by the virtual machine.

isThreadContentionMonitoringEnabled

public boolean isThreadContentionMonitoringEnabled()
Returns true if thread contention monitoring is currently enabled.
Specified by:
isThreadContentionMonitoringEnabled in interface ThreadMXBean
Returns:
true if thread contention monitoring is enabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support contention monitoring.

isThreadContentionMonitoringSupported

public boolean isThreadContentionMonitoringSupported()
Returns true if thread contention monitoring is supported by the virtual machine.
Specified by:
isThreadContentionMonitoringSupported in interface ThreadMXBean
Returns:
true if thread contention monitoring is supported by the virtual machine.

isThreadCpuTimeEnabled

public boolean isThreadCpuTimeEnabled()
Returns true if monitoring of the CPU time used by a thread is currently enabled.
Specified by:
isThreadCpuTimeEnabled in interface ThreadMXBean
Returns:
true if thread CPU time monitoring is enabled.
Throws:
UnsupportedOperationException - if the virtual machine does not support CPU time monitoring.

isThreadCpuTimeSupported

public 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.
Specified by:
isThreadCpuTimeSupported in interface ThreadMXBean
Returns:
true if monitoring of the CPU time used by the current thread is supported by the virtual machine.

resetPeakThreadCount

public void resetPeakThreadCount()
Resets the peak live thread count to the current number of live threads, as returned by ThreadMXBean.getThreadCount().
Specified by:
resetPeakThreadCount in interface ThreadMXBean
Throws:
SecurityException - if a security manager exists and denies ManagementPermission("control").

setThreadContentionMonitoringEnabled

public 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.
Specified by:
setThreadContentionMonitoringEnabled in interface ThreadMXBean
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").

setThreadCpuTimeEnabled

public 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.
Specified by:
setThreadCpuTimeEnabled in interface ThreadMXBean
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").

ThreadMXBeanImpl.java - Implementation of a thread bean Copyright (C) 2006 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.