From 6e3287e85161666773fdc9016ba6ce19ba1bf6ec Mon Sep 17 00:00:00 2001 From: Andrew John Hughes Date: Mon, 26 Jun 2006 20:56:58 +0000 Subject: 2006-06-26 Andrew John Hughes * java/lang/Thread.java: (getState()): New method. * java/lang/management/ClassLoadingMXBean.java: Corrected class documentation. * java/lang/management/ManagementFactory.java: Added new temporary marked stub to get thread bean. * java/lang/management/OperatingSystemMXBean.java: Corrected class documentation. * java/lang/management/RuntimeMXBean.java: Corrected class documentation. * java/lang/management/ThreadInfo.java, * java/lang/management/ThreadMXBean.java: New classes. * vm/reference/java/lang/VMThread.java: (getState()): New method. * vm/reference/java/lang/management/VMThreadInfo.java: New VM class. --- java/lang/Thread.java | 14 + java/lang/management/ClassLoadingMXBean.java | 2 +- java/lang/management/ManagementFactory.java | 17 +- java/lang/management/OperatingSystemMXBean.java | 2 +- java/lang/management/RuntimeMXBean.java | 2 +- java/lang/management/ThreadInfo.java | 405 +++++++++++++++++++ java/lang/management/ThreadMXBean.java | 497 ++++++++++++++++++++++++ 7 files changed, 935 insertions(+), 4 deletions(-) create mode 100644 java/lang/management/ThreadInfo.java create mode 100644 java/lang/management/ThreadMXBean.java (limited to 'java') diff --git a/java/lang/Thread.java b/java/lang/Thread.java index 74d24633b..df4c65ece 100644 --- a/java/lang/Thread.java +++ b/java/lang/Thread.java @@ -1221,4 +1221,18 @@ public class Thread implements Runnable */ void uncaughtException(Thread thr, Throwable exc); } + + /** + * Returns the current state of the thread. This + * is designed for monitoring thread behaviour, rather + * than for synchronization control. + * + * @return the current thread state. + */ + public String getState() + { + VMThread t = vmThread; + return t == null ? null : t.getState(); + } + } diff --git a/java/lang/management/ClassLoadingMXBean.java b/java/lang/management/ClassLoadingMXBean.java index e11c9bb60..2a8651b9c 100644 --- a/java/lang/management/ClassLoadingMXBean.java +++ b/java/lang/management/ClassLoadingMXBean.java @@ -40,7 +40,7 @@ package java.lang.management; /** * Provides access to information about the class loading * behaviour of the current invocation of the virtual - * machine. Instances of this bean are obtained by calling + * machine. An instance of this bean is obtained by calling * {@link ManagementFactory#getClassLoadingMXBean()}. * * @author Andrew John Hughes (gnu_andrew@member.fsf.org) diff --git a/java/lang/management/ManagementFactory.java b/java/lang/management/ManagementFactory.java index a5a2d6acf..5f99bbe1d 100644 --- a/java/lang/management/ManagementFactory.java +++ b/java/lang/management/ManagementFactory.java @@ -37,6 +37,8 @@ exception statement from your version. */ package java.lang.management; +import gnu.classpath.NotImplementedException; + import gnu.java.lang.management.ClassLoadingMXBeanImpl; import gnu.java.lang.management.OperatingSystemMXBeanImpl; import gnu.java.lang.management.RuntimeMXBeanImpl; @@ -122,5 +124,18 @@ public class ManagementFactory classLoadingBean = new ClassLoadingMXBeanImpl(); return classLoadingBean; } - + + /** + * Returns the thread management bean for the running + * virtual machine. + * + * @return an instance of {@link ThreadMXBean} for + * this virtual machine. + */ + public static ThreadMXBean getThreadMXBean() + throws NotImplementedException + { + return null; + } + } diff --git a/java/lang/management/OperatingSystemMXBean.java b/java/lang/management/OperatingSystemMXBean.java index 74b9ae5a1..2430a9fbf 100644 --- a/java/lang/management/OperatingSystemMXBean.java +++ b/java/lang/management/OperatingSystemMXBean.java @@ -39,7 +39,7 @@ package java.lang.management; /** * Provides access to information about the underlying operating - * system. Instances of this bean are obtained by calling + * system. An instance of this bean is obtained by calling * {@link ManagementFactory#getOperatingSystemMXBean()}. * * @author Andrew John Hughes (gnu_andrew@member.fsf.org) diff --git a/java/lang/management/RuntimeMXBean.java b/java/lang/management/RuntimeMXBean.java index 1aab6bb09..cee1d805f 100644 --- a/java/lang/management/RuntimeMXBean.java +++ b/java/lang/management/RuntimeMXBean.java @@ -42,7 +42,7 @@ import java.util.Map; /** * Provides access to information about the underlying virtual - * machine. Instances of this bean are obtained by calling + * machine. An instance of this bean is obtained by calling * {@link ManagementFactory#getRuntimeMXBean()}. * * @author Andrew John Hughes (gnu_andrew@member.fsf.org) diff --git a/java/lang/management/ThreadInfo.java b/java/lang/management/ThreadInfo.java new file mode 100644 index 000000000..a5555cbe6 --- /dev/null +++ b/java/lang/management/ThreadInfo.java @@ -0,0 +1,405 @@ +/* ThreadInfo.java - Information on a thread + 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. */ + +package java.lang.management; + +/** + *

+ * A class which maintains information about a particular + * thread. This information includes: + *

+ * + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.5 + * @see ThreadMXBean#isThreadContentionMonitoringSupported() + */ +public class ThreadInfo +{ + + /** + * The thread which this instance concerns. + */ + private Thread thread; + + /** + * The maximum depth of the stack traces for this thread. + */ + private int maxDepth; + + /** + * Cache a local reference to the thread management bean. + */ + private static ThreadMXBean bean = null; + + /** + * Constructs a new {@link ThreadInfo} corresponding + * to the thread specified. + * + * @param thread the thread on which the new instance + * will be based. + */ + ThreadInfo(Thread thread, int maxDepth) + { + this.thread = thread; + this.maxDepth = maxDepth; + } + + /** + * Returns the number of times this thread has been + * in the {@link java.lang.Thread.State#BLOCKED} state. + * A thread enters this state when it is waiting to + * obtain an object's monitor. This may occur either + * on entering a synchronized method for the first time, + * or on re-entering it following a call to + * {@link java.lang.Object#wait()}. + * + * @return the number of times this thread has been blocked. + */ + public long getBlockedCount() + { + return VMThreadInfo.getBlockedCount(thread); + } + + /** + *

+ * Returns the accumulated number of milliseconds this + * thread has been in the + * {@link java.lang.Thread.State#BLOCKED} state + * since thread contention monitoring was last enabled. + * A thread enters this state when it is waiting to + * obtain an object's monitor. This may occur either + * on entering a synchronized method for the first time, + * or on re-entering it following a call to + * {@link java.lang.Object#wait()}. + *

+ *

+ * Use of this method requires virtual machine support + * for thread contention monitoring and for this support + * to be enabled. + *

+ * + * @return the accumulated time (in milliseconds) that this + * thread has spent in the blocked state, since + * thread contention monitoring was enabled, or -1 + * if thread contention monitoring is disabled. + * @throws UnsupportedOperationException if the virtual + * machine does not + * support contention + * monitoring. + * @see ThreadMXBean#isThreadContentionMonitoringEnabled() + * @see ThreadMXBean#isThreadContentionMonitoringSupported() + */ + public long getBlockedTime() + { + if (bean == null) + bean = ManagementFactory.getThreadMXBean(); + // Will throw UnsupportedOperationException for us + if (bean.isThreadContentionMonitoringEnabled()) + return VMThreadInfo.getBlockedTime(thread); + else + return -1; + } + + /** + *

+ * Returns a {@link java.lang.String} representation of + * the monitor lock on which this thread is blocked. If + * the thread is not blocked, this method returns + * null. + *

+ *

+ * The returned {@link java.lang.String} is constructed + * using the class name and identity hashcode (usually + * the memory address of the object) of the lock. The + * two are separated by the '@' character, and the identity + * hashcode is represented in hexadecimal. Thus, for a + * lock, l, the returned value is + * the result of concatenating + * l.getClass().getName(), "@" + * and + * Integer.toHexString(System.identityHashCode(l)). + * The value is only unique to the extent that the identity + * hash code is also unique. + *

+ * + * @return a string representing the lock on which this + * thread is blocked, or null if + * the thread is not blocked. + */ + public String getLockName() + { + if (thread.getState().equals("BLOCKED")) + return null; + Object lock = VMThreadInfo.getLock(thread); + return lock.getClass().getName() + "@" + + Integer.toHexString(System.identityHashCode(lock)); + } + + /** + * Returns the identifier of the thread which owns the + * monitor lock this thread is waiting for. -1 is returned + * if either this thread is not blocked, or the lock is + * not held by any other thread. + * + * @return the thread identifier of thread holding the lock + * this thread is waiting for, or -1 if the thread + * is not blocked or the lock is not held by another + * thread. + */ + public long getLockOwnerId() + { + if (thread.getState().equals("BLOCKED")) + return -1; + Thread lockOwner = VMThreadInfo.getLockOwner(thread); + if (lockOwner == null) + return -1; + return lockOwner.getId(); + } + + /** + * Returns the name of the thread which owns the + * monitor lock this thread is waiting for. null + * is returned if either this thread is not blocked, + * or the lock is not held by any other thread. + * + * @return the thread identifier of thread holding the lock + * this thread is waiting for, or null + * if the thread is not blocked or the lock is not + * held by another thread. + */ + public String getLockOwnerName() + { + if (thread.getState().equals("BLOCKED")) + return null; + Thread lockOwner = VMThreadInfo.getLockOwner(thread); + if (lockOwner == null) + return null; + return lockOwner.getName(); + } + + /** + *

+ * Returns the stack trace of this thread to the depth + * specified on creation of this {@link ThreadInfo} + * object. If the depth is zero, an empty array will + * be returned. For non-zero arrays, the elements + * start with the most recent trace at position zero. + * The bottom of the stack represents the oldest method + * invocation which meets the depth requirements. + *

+ *

+ * Some virtual machines may not be able to return + * stack trace information for a thread. In these + * cases, an empty array will also be returned. + *

+ * + * @return an array of {@link java.lang.StackTraceElement}s + * representing the trace of this thread. + */ + public StackTraceElement[] getStackTrace() + { + if (maxDepth == 0) + return new StackTraceElement[0]; + return VMThreadInfo.getStackTrace(thread, maxDepth); + } + + /** + * Returns the identifier of the thread associated with + * this instance of {@link ThreadInfo}. + * + * @return the thread's identifier. + */ + public long getThreadId() + { + return thread.getId(); + } + + /** + * Returns the name of the thread associated with + * this instance of {@link ThreadInfo}. + * + * @return the thread's name. + */ + public String getThreadName() + { + return thread.getName(); + } + + /** + * Returns the state of the thread associated with + * this instance of {@link ThreadInfo}. + * + * @return the thread's state. + */ + public String getThreadState() + { + return thread.getState(); + } + + /** + * Returns the number of times this thread has been + * in the {@link java.lang.Thread.State#WAITING} + * or {@link java.lang.Thread.State#TIMED_WAITING} state. + * A thread enters one of these states when it is waiting + * due to a call to {@link java.lang.Object.wait()}, + * {@link java.lang.Object.join()} or + * {@link java.lang.concurrent.locks.LockSupport.park()}, + * either with an infinite or timed delay, respectively. + * + * @return the number of times this thread has been waiting. + */ + public long getWaitedCount() + { + return VMThreadInfo.getWaitedCount(thread); + } + + /** + *

+ * Returns the accumulated number of milliseconds this + * thread has been in the + * {@link java.lang.Thread.State#WAITING} or + * {@link java.lang.Thread.State#TIMED_WAITING} state, + * since thread contention monitoring was last enabled. + * A thread enters one of these states when it is waiting + * due to a call to {@link java.lang.Object.wait()}, + * {@link java.lang.Object.join()} or + * {@link java.lang.concurrent.locks.LockSupport.park()}, + * either with an infinite or timed delay, respectively. + *

+ *

+ * Use of this method requires virtual machine support + * for thread contention monitoring and for this support + * to be enabled. + *

+ * + * @return the accumulated time (in milliseconds) that this + * thread has spent in one of the waiting states, since + * thread contention monitoring was enabled, or -1 + * if thread contention monitoring is disabled. + * @throws UnsupportedOperationException if the virtual + * machine does not + * support contention + * monitoring. + * @see ThreadMXBean#isThreadContentionMonitoringEnabled() + * @see ThreadMXBean#isThreadContentionMonitoringSupported() + */ + public long getWaitedTime() + { + if (bean == null) + bean = ManagementFactory.getThreadMXBean(); + // Will throw UnsupportedOperationException for us + if (bean.isThreadContentionMonitoringEnabled()) + return VMThreadInfo.getWaitedTime(thread); + else + return -1; + } + + /** + * Returns true if the thread is in a native method. This + * excludes native code which forms part of the virtual + * machine itself, or which results from Just-In-Time + * compilation. + * + * @return true if the thread is in a native method, false + * otherwise. + */ + public boolean isInNative() + { + return VMThreadInfo.isInNative(thread); + } + + /** + * Returns true if the thread has been suspended using + * {@link java.lang.Thread#suspend()}. + * + * @return true if the thread is suspended, false otherwise. + */ + public boolean isSuspended() + { + return VMThreadInfo.isSuspended(thread); + } + + /** + * Returns a {@link java.lang.String} representation of + * this {@link ThreadInfo} object. This takes the form + * java.lang.ThreadInfo[id=tid, maxDepth=md], + * where tid is the thread identifier + * and md is the maximum depth used by + * this {@link ThreadInfo}. + * + * @return the string specified above. + */ + public String toString() + { + return getClass().getName() + + "[id=" + thread.getId() + ", maxDepth=" + + maxDepth + "]"; + } + +} diff --git a/java/lang/management/ThreadMXBean.java b/java/lang/management/ThreadMXBean.java new file mode 100644 index 000000000..4e40e7fd3 --- /dev/null +++ b/java/lang/management/ThreadMXBean.java @@ -0,0 +1,497 @@ +/* ThreadMXBean.java - Interface for 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. */ + +package java.lang.management; + +/** + *

+ * 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. + *

+ * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.5 + */ +public interface ThreadMXBean +{ + + /** + *

+ * 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. + *

+ * + * @return 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"). + */ + long[] findMonitorDeadlockedThreads(); + + /** + * 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. + * + * @return an array of thread identifiers, corresponding to + * current live threads. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("monitor"). + */ + long[] getAllThreadIds(); + + /** + *

+ * 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. + *

+ * + * @return 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 #getCurrentThreadUserTime() + * @see #isCurrentThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #setThreadCpuTimeEnabled(boolean) + */ + long getCurrentThreadCpuTime(); + + /** + *

+ * 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. + *

+ * + * @return 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 #getCurrentThreadCpuTime() + * @see #isCurrentThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #setThreadCpuTimeEnabled(boolean) + */ + long getCurrentThreadUserTime(); + + /** + * Returns the number of live daemon threads. + * + * @return the number of live daemon threads. + */ + int getDaemonThreadCount(); + + /** + * Returns the peak number of live threads since + * the virtual machine was started or the count + * reset using {@link #resetPeakThreadCount()}. + * + * @return the peak live thread count. + * @see #resetPeakThreadCount() + */ + int getPeakThreadCount(); + + /** + * Returns the number of live threads, including + * both daemon threads and non-daemon threads. + * + * @return the current number of live threads. + */ + int getThreadCount(); + + /** + *

+ * 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. + *

+ * + * @param id the thread identifier of the thread whose CPU time is being + * monitored. + * @return 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. + * @throws UnsupportedOperationException if CPU time monitoring is not + * supported. + * @see #getThreadUserTime(long) + * @see #isThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #setThreadCpuTimeEnabled(boolean) + */ + long getThreadCpuTime(long id); + + /** + * Returns information on the specified thread without any + * stack trace information. This is equivalent to + * {@link #getThreadInfo}(id, 0). If the + * identifier specifies a thread which is either non-existant + * or not alive, then the method returns null. + * + * @param id the identifier of the thread to return information + * on. + * @return 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. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("monitor"). + */ + ThreadInfo getThreadInfo(long id); + + /** + * Returns information on the specified threads without any + * stack trace information. This is equivalent to + * {@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. + * + * @param ids an array of thread identifiers to return information + * on. + * @return 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. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("monitor"). + */ + ThreadInfo getThreadInfo(long[] ids); + + /** + * 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 + * {@link ThreadInfo} method). A maximum depth of + * Integer.MAX_VALUE returns the full stack trace. + * + * @param id the identifier of the thread to return information + * on. + * @param maxDepth the maximum depth of the stack trace. + * Values of 0 or Integer.MAX_VALUE + * correspond to an empty and full stack trace + * respectively. + * @return 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. + * @throws IllegalArgumentException if maxDepth <= 0. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("monitor"). + */ + ThreadInfo getThreadInfo(long id, 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 {@link ThreadInfo} method). A maximum depth of + * Integer.MAX_VALUE returns the full stack trace. + * + * @param ids an array of thread identifiers to return information + * on. + * @param maxDepth the maximum depth of the stack trace. + * Values of 0 or Integer.MAX_VALUE + * correspond to an empty and full stack trace + * respectively. + * @return 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. + * @throws IllegalArgumentException if maxDepth <= 0. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("monitor"). + */ + ThreadInfo getThreadInfo(long[] ids, int maxDepth); + + /** + *

+ * 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. + *

+ * + * @param id the thread identifier of the thread whose CPU time is being + * monitored. + * @return 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. + * @throws UnsupportedOperationException if CPU time monitoring is not + * supported. + * @see #getThreadCpuTime(long) + * @see #isThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #setThreadCpuTimeEnabled(boolean) + */ + long getThreadUserTime(long id); + + /** + * Returns the total number of threads that have been + * created and started during the lifetime of the virtual + * machine. + * + * @return the total number of started threads. + */ + long getTotalStartedThreadCount(); + + /** + * Returns true if the virtual machine supports the monitoring + * of the CPU time used by the current thread. This is implied + * by {@link isThreadCpuTimeSupported()} returning true. + * + * @return true if monitoring of the CPU time used by the current + * thread is supported by the virtual machine. + * @see #isThreadCpuTimeEnabled() + * @see #isThreadCpuTimeSupported() + * @see #setThreadCpuTimeEnabled(boolean) + */ + boolean isCurrentThreadCpuTimeSupported(); + + /** + * Returns true if thread contention monitoring is currently + * enabled. + * + * @return true if thread contention monitoring is enabled. + * @throws UnsupportedOperationException if the virtual + * machine does not + * support contention + * monitoring. + * @see #isThreadContentionMonitoringSupported() + * @see #setThreadContentionMonitoringEnabled(boolean) + */ + boolean isThreadContentionMonitoringEnabled(); + + /** + * Returns true if thread contention monitoring is supported + * by the virtual machine. + * + * @return true if thread contention monitoring is supported + * by the virtual machine. + * @see #isThreadContentionMonitoringEnabled() + * @see #setThreadContentionMonitoringEnabled(boolean) + */ + boolean isThreadContentionMonitoringSupported(); + + /** + * Returns true if monitoring of the CPU time used by a thread + * is currently enabled. + * + * @return true if thread CPU time monitoring is enabled. + * @throws UnsupportedOperationException if the virtual + * machine does not + * support CPU time + * monitoring. + * @see #isCurrentThreadCpuTimeSupported() + * @see #isThreadCpuTimeSupported() + * @see #setThreadCpuTimeEnabled(boolean) + */ + boolean isThreadCpuTimeEnabled(); + + /** + * Returns true if the virtual machine supports the monitoring + * of the CPU time used by all threads. This implies + * that {@link isCurrentThreadCpuTimeSupported()} returns true. + * + * @return true if monitoring of the CPU time used by the current + * thread is supported by the virtual machine. + * @see #isCurrentThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #setThreadCpuTimeEnabled(boolean) + */ + boolean isThreadCpuTimeSupported(); + + /** + * Resets the peak live thread count to the + * current number of live threads, as returned + * by {@link #getThreadCount()}. + * + * @see #getPeakThreadCount() + * @see #getThreadCount() + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("control"). + */ + void resetPeakThreadCount(); + + /** + * 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. + * + * @param enable true if monitoring should be enabled, + * false if it should be disabled. + * @throws UnsupportedOperationException if the virtual + * machine does not + * support contention + * monitoring. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("control"). + * @see #isThreadContentionMonitoringEnabled() + * @see #isThreadContentionMonitoringSupported() + */ + void setThreadContentionMonitoringEnabled(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. + * + * @param 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. + * @throws SecurityException if a security manager exists and + * denies ManagementPermission("control"). + * @see #isCurrentThreadCpuTimeSupported() + * @see #isThreadCpuTimeEnabled() + * @see #isThreadCpuTimeSupported() + */ + void setThreadCpuTimeEnabled(boolean enable); + +} -- cgit v1.2.1