This is the first part of the threading management bean. It doesn't yet include the bean; I've stubbed this in the management factory temporarily as this patch is already fairly large without that bit.
With just the public interface, both the bean interface and a
new class, ThreadInfo, are added. The latter also has a new
VM interface, which is included here. Some of this is optional
if the VM doesn't implement contention monitoring (see the bean).
Most of this depends on the state of the thread, which it appears
we don't as yet have. This patch thus also includes the addition
of a new native method to the VMThread interface to obtain the state.
Due to this being an enumeration in 1.5, we simply use a String here
and take the JAPI warnings on the chest. The VM layer one is likely to
remain a String anyway, as it is simpler to pass around in native
code (I presume; correct me if I'm wrong). When I merge this to the
generics branch, I'll convert the top layer to use the enumeration.
Unfortunately, we do need this on both branches to keep the VM layers
in sync.
It appears we are still missing quite a bit of the new thread functionality.
There are also methods for stack traces, which I will implement shortly;
from what I can see, we only need the one in ThreadInfo specified here; this
can be used to also fulfill the methods in Thread. Identifiers have been
implemented
in Thread, but I'm not sure if this is correct -- mainly because we need to
be able to map thread identifiers to threads for the bean. I'll take a look
at this further when I implement the bean, but it seems even non-Java-created
threads will need an id.
Anyway, here's the patch:
Changelog:
2006-06-26 Andrew John Hughes <[EMAIL PROTECTED]>
* 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.
--
Andrew :-)
Please avoid sending me Microsoft Office (e.g. Word, PowerPoint) attachments.
See http://www.fsf.org/philosophy/no-word-attachments.html
If you use Microsoft Office, support movement towards the end of vendor lock-in:
http://opendocumentfellowship.org/petition/
"Value your freedom, or you will lose it, teaches history.
`Don't bother us with politics' respond those who don't want to learn."
-- Richard Stallman
Escape the Java Trap with GNU Classpath!
http://www.gnu.org/philosophy/java-trap.html
public class gcj extends Freedom implements Java { ... }
Index: java/lang/Thread.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/Thread.java,v
retrieving revision 1.24
diff -u -3 -p -u -r1.24 Thread.java
--- java/lang/Thread.java 12 Jun 2006 14:36:05 -0000 1.24
+++ java/lang/Thread.java 26 Jun 2006 20:44:17 -0000
@@ -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();
+ }
+
}
Index: java/lang/management/ClassLoadingMXBean.java
===================================================================
RCS file:
/cvsroot/classpath/classpath/java/lang/management/ClassLoadingMXBean.java,v
retrieving revision 1.2
diff -u -3 -p -u -r1.2 ClassLoadingMXBean.java
--- java/lang/management/ClassLoadingMXBean.java 25 Jun 2006 16:54:57
-0000 1.2
+++ java/lang/management/ClassLoadingMXBean.java 26 Jun 2006 20:44:17
-0000
@@ -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
* [EMAIL PROTECTED] ManagementFactory#getClassLoadingMXBean()}.
*
* @author Andrew John Hughes ([EMAIL PROTECTED])
Index: java/lang/management/ManagementFactory.java
===================================================================
RCS file:
/cvsroot/classpath/classpath/java/lang/management/ManagementFactory.java,v
retrieving revision 1.4
diff -u -3 -p -u -r1.4 ManagementFactory.java
--- java/lang/management/ManagementFactory.java 25 Jun 2006 00:52:34 -0000
1.4
+++ java/lang/management/ManagementFactory.java 26 Jun 2006 20:44:17 -0000
@@ -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 [EMAIL PROTECTED] ThreadMXBean} for
+ * this virtual machine.
+ */
+ public static ThreadMXBean getThreadMXBean()
+ throws NotImplementedException
+ {
+ return null;
+ }
+
}
Index: java/lang/management/OperatingSystemMXBean.java
===================================================================
RCS file:
/cvsroot/classpath/classpath/java/lang/management/OperatingSystemMXBean.java,v
retrieving revision 1.1
diff -u -3 -p -u -r1.1 OperatingSystemMXBean.java
--- java/lang/management/OperatingSystemMXBean.java 28 May 2006 15:04:15
-0000 1.1
+++ java/lang/management/OperatingSystemMXBean.java 26 Jun 2006 20:44:17
-0000
@@ -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
* [EMAIL PROTECTED] ManagementFactory#getOperatingSystemMXBean()}.
*
* @author Andrew John Hughes ([EMAIL PROTECTED])
Index: java/lang/management/RuntimeMXBean.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/management/RuntimeMXBean.java,v
retrieving revision 1.2
diff -u -3 -p -u -r1.2 RuntimeMXBean.java
--- java/lang/management/RuntimeMXBean.java 11 Jun 2006 21:57:15 -0000
1.2
+++ java/lang/management/RuntimeMXBean.java 26 Jun 2006 20:44:17 -0000
@@ -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
* [EMAIL PROTECTED] ManagementFactory#getRuntimeMXBean()}.
*
* @author Andrew John Hughes ([EMAIL PROTECTED])
Index: java/lang/management/ThreadInfo.java
===================================================================
RCS file: java/lang/management/ThreadInfo.java
diff -N java/lang/management/ThreadInfo.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ java/lang/management/ThreadInfo.java 26 Jun 2006 20:44:17 -0000
@@ -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;
+
+/**
+ * <p>
+ * A class which maintains information about a particular
+ * thread. This information includes:
+ * </p>
+ * <ul>
+ * <li><strong>General Thread Information:</strong>
+ * <ul>
+ * <li>The identifier of the thread.</li>
+ * <li>The name of the thread.</li>
+ * </ul>
+ * </li>
+ * <li><strong>Execution Information:</strong>
+ * <ul>
+ * <li>The current state of the thread (e.g. blocked, runnable)</li>
+ * <li>The object upon which the thread is blocked, either because
+ * the thread is waiting to obtain the monitor of that object to enter
+ * one of its synchronized monitor, or because
+ * [EMAIL PROTECTED] java.lang.Object#wait()} has been called while the thread
+ * was within a method of that object.</li>
+ * <li>The thread identifier of the current thread holding an object's
+ * monitor, upon which the thread described here is blocked.</li>
+ * <li>The stack trace of the thread (if requested on creation
+ * of this object</li>
+ * </ul>
+ * <li><strong>Synchronization Statistics</strong>
+ * <ul>
+ * <li>The number of times the thread has been blocked waiting for
+ * an object's monitor or in a [EMAIL PROTECTED] java.lang.Object#wait()}
call.</li>
+ * <li>The accumulated time the thread has been blocked waiting for
+ * an object's monitor on in a [EMAIL PROTECTED] java.lang.Object#wait()} call.
+ * The availability of these statistics depends on the virtual machine's
+ * support for thread contention monitoring (see
+ * [EMAIL PROTECTED]
ThreadMXBean#isThreadContentionMonitoringSupported()}.</li>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * @author Andrew John Hughes ([EMAIL PROTECTED])
+ * @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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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
+ * [EMAIL PROTECTED] java.lang.Object#wait()}.
+ *
+ * @return the number of times this thread has been blocked.
+ */
+ public long getBlockedCount()
+ {
+ return VMThreadInfo.getBlockedCount(thread);
+ }
+
+ /**
+ * <p>
+ * Returns the accumulated number of milliseconds this
+ * thread has been in the
+ * [EMAIL PROTECTED] 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
+ * [EMAIL PROTECTED] java.lang.Object#wait()}.
+ * </p>
+ * <p>
+ * Use of this method requires virtual machine support
+ * for thread contention monitoring and for this support
+ * to be enabled.
+ * </p>
+ *
+ * @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;
+ }
+
+ /**
+ * <p>
+ * Returns a [EMAIL PROTECTED] java.lang.String} representation of
+ * the monitor lock on which this thread is blocked. If
+ * the thread is not blocked, this method returns
+ * <code>null</code>.
+ * </p>
+ * <p>
+ * The returned [EMAIL PROTECTED] 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, <code>l</code>, the returned value is
+ * the result of concatenating
+ * <code>l.getClass().getName()</code>, <code>"@"</code>
+ * and
+ * <code>Integer.toHexString(System.identityHashCode(l))</code>.
+ * The value is only unique to the extent that the identity
+ * hash code is also unique.
+ * </p>
+ *
+ * @return a string representing the lock on which this
+ * thread is blocked, or <code>null</code> 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. <code>null</code>
+ * 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 <code>null</code>
+ * 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();
+ }
+
+ /**
+ * <p>
+ * Returns the stack trace of this thread to the depth
+ * specified on creation of this [EMAIL PROTECTED] 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @return an array of [EMAIL PROTECTED] 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 [EMAIL PROTECTED] ThreadInfo}.
+ *
+ * @return the thread's identifier.
+ */
+ public long getThreadId()
+ {
+ return thread.getId();
+ }
+
+ /**
+ * Returns the name of the thread associated with
+ * this instance of [EMAIL PROTECTED] ThreadInfo}.
+ *
+ * @return the thread's name.
+ */
+ public String getThreadName()
+ {
+ return thread.getName();
+ }
+
+ /**
+ * Returns the state of the thread associated with
+ * this instance of [EMAIL PROTECTED] ThreadInfo}.
+ *
+ * @return the thread's state.
+ */
+ public String getThreadState()
+ {
+ return thread.getState();
+ }
+
+ /**
+ * Returns the number of times this thread has been
+ * in the [EMAIL PROTECTED] java.lang.Thread.State#WAITING}
+ * or [EMAIL PROTECTED] java.lang.Thread.State#TIMED_WAITING} state.
+ * A thread enters one of these states when it is waiting
+ * due to a call to [EMAIL PROTECTED] java.lang.Object.wait()},
+ * [EMAIL PROTECTED] java.lang.Object.join()} or
+ * [EMAIL PROTECTED] 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);
+ }
+
+ /**
+ * <p>
+ * Returns the accumulated number of milliseconds this
+ * thread has been in the
+ * [EMAIL PROTECTED] java.lang.Thread.State#WAITING} or
+ * [EMAIL PROTECTED] 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 [EMAIL PROTECTED] java.lang.Object.wait()},
+ * [EMAIL PROTECTED] java.lang.Object.join()} or
+ * [EMAIL PROTECTED] java.lang.concurrent.locks.LockSupport.park()},
+ * either with an infinite or timed delay, respectively.
+ * </p>
+ * <p>
+ * Use of this method requires virtual machine support
+ * for thread contention monitoring and for this support
+ * to be enabled.
+ * </p>
+ *
+ * @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
+ * [EMAIL PROTECTED] java.lang.Thread#suspend()}.
+ *
+ * @return true if the thread is suspended, false otherwise.
+ */
+ public boolean isSuspended()
+ {
+ return VMThreadInfo.isSuspended(thread);
+ }
+
+ /**
+ * Returns a [EMAIL PROTECTED] java.lang.String} representation of
+ * this [EMAIL PROTECTED] ThreadInfo} object. This takes the form
+ * <code>java.lang.ThreadInfo[id=tid, maxDepth=md]</code>,
+ * where <code>tid</code> is the thread identifier
+ * and <code>md</code> is the maximum depth used by
+ * this [EMAIL PROTECTED] ThreadInfo}.
+ *
+ * @return the string specified above.
+ */
+ public String toString()
+ {
+ return getClass().getName() +
+ "[id=" + thread.getId() + ", maxDepth=" +
+ maxDepth + "]";
+ }
+
+}
Index: java/lang/management/ThreadMXBean.java
===================================================================
RCS file: java/lang/management/ThreadMXBean.java
diff -N java/lang/management/ThreadMXBean.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ java/lang/management/ThreadMXBean.java 26 Jun 2006 20:44:17 -0000
@@ -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;
+
+/**
+ * <p>
+ * Provides access to information about the threads
+ * of the virtual machine. An instance of this bean is
+ * obtained by calling
+ * [EMAIL PROTECTED] ManagementFactory#getThreadMXBean()}.
+ * </p>
+ * <p>
+ * 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 [EMAIL PROTECTED] 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).
+ * </p>
+ * <p>
+ * 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
+ * [EMAIL PROTECTED] #isThreadCpuTimeSupported()},
+ * [EMAIL PROTECTED] #isCurrentThreadCpuTimeSupported()} and
+ * [EMAIL PROTECTED] #isThreadContentionMonitoringSupported()} may be
+ * used to determine whether or not this functionality is
+ * supported.
+ * </p>
+ * <p>
+ * 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 [EMAIL PROTECTED] #setThreadContentionMonitoringEnabled(boolean)}
+ * method.
+ * </p>
+ *
+ * @author Andrew John Hughes ([EMAIL PROTECTED])
+ * @since 1.5
+ */
+public interface ThreadMXBean
+{
+
+ /**
+ * <p>
+ * 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
+ * [EMAIL PROTECTED] java.lang.Object#wait()} call, a thread obtains
ownership
+ * of the object's monitor.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @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();
+
+ /**
+ * <p>
+ * Returns the total number of nanoseconds of CPU time
+ * the current thread has used. This is equivalent to calling
+ * <code>[EMAIL PROTECTED]
#getThreadCpuTime()}(Thread.currentThread.getId())</code>.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @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();
+
+ /**
+ * <p>
+ * Returns the total number of nanoseconds of CPU time
+ * the current thread has executed in user mode. This is
+ * equivalent to calling
+ * <code>[EMAIL PROTECTED]
#getThreadUserTime()}(Thread.currentThread.getId())</code>.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @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 [EMAIL PROTECTED] #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();
+
+ /**
+ * <p>
+ * Returns the total number of nanoseconds of CPU time
+ * the specified thread has used.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @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 <code>id</code> <= 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
+ * <code>[EMAIL PROTECTED] #getThreadInfo}(id, 0)</code>. If the
+ * identifier specifies a thread which is either non-existant
+ * or not alive, then the method returns <code>null</code>.
+ *
+ * @param id the identifier of the thread to return information
+ * on.
+ * @return a [EMAIL PROTECTED] ThreadInfo} object pertaining to the specified
+ * thread, or <code>null</code> if the identifier specifies
+ * a thread that doesn't exist or is not alive.
+ * @throws IllegalArgumentException if <code>id</code> <= 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
+ * <code>[EMAIL PROTECTED] #getThreadInfo}(ids, 0)</code>. If an
+ * identifier specifies a thread which is either non-existant
+ * or not alive, then the corresponding element in the returned
+ * array is <code>null</code>.
+ *
+ * @param ids an array of thread identifiers to return information
+ * on.
+ * @return an array of [EMAIL PROTECTED] ThreadInfo} objects matching the
+ * specified threads. The corresponding element is
+ * <code>null</code> 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 <code>null</code>.
+ * A maximum depth of 0 corresponds to an empty stack trace
+ * (an empty array is returned by the appropriate
+ * [EMAIL PROTECTED] ThreadInfo} method). A maximum depth of
+ * <code>Integer.MAX_VALUE</code> 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 <code>Integer.MAX_VALUE</code>
+ * correspond to an empty and full stack trace
+ * respectively.
+ * @return a [EMAIL PROTECTED] ThreadInfo} object pertaining to the specified
+ * thread, or <code>null</code> if the identifier specifies
+ * a thread that doesn't exist or is not alive.
+ * @throws IllegalArgumentException if <code>id</code> <= 0.
+ * @throws IllegalArgumentException if <code>maxDepth</code> <= 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 <code>null</code>. A maximum depth of 0 corresponds
+ * to an empty stack trace (an empty array is returned by the
+ * appropriate [EMAIL PROTECTED] ThreadInfo} method). A maximum depth of
+ * <code>Integer.MAX_VALUE</code> 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 <code>Integer.MAX_VALUE</code>
+ * correspond to an empty and full stack trace
+ * respectively.
+ * @return an array of [EMAIL PROTECTED] ThreadInfo} objects matching the
+ * specified threads. The corresponding element is
+ * <code>null</code> 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 <code>maxDepth</code> <= 0.
+ * @throws SecurityException if a security manager exists and
+ * denies ManagementPermission("monitor").
+ */
+ ThreadInfo getThreadInfo(long[] ids, int maxDepth);
+
+ /**
+ * <p>
+ * Returns the total number of nanoseconds of CPU time
+ * the specified thread has executed in user mode.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @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 <code>id</code> <= 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #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);
+
+}
Index: vm/reference/java/lang/VMThread.java
===================================================================
RCS file: /cvsroot/classpath/classpath/vm/reference/java/lang/VMThread.java,v
retrieving revision 1.11
diff -u -3 -p -u -r1.11 VMThread.java
--- vm/reference/java/lang/VMThread.java 14 Apr 2006 07:51:42 -0000
1.11
+++ vm/reference/java/lang/VMThread.java 26 Jun 2006 20:44:22 -0000
@@ -446,4 +446,16 @@ final class VMThread
return false;
}
}
+
+ /**
+ * Returns the current state of the thread.
+ * The value must be one of "BLOCKED", "NEW",
+ * "RUNNABLE", "TERMINATED", "TIMED_WAITING" or
+ * "WAITING".
+ *
+ * @return a string corresponding to one of the
+ * thread enumeration states specified above.
+ */
+ native String getState();
+
}
Index: vm/reference/java/lang/management/VMThreadInfo.java
===================================================================
RCS file: vm/reference/java/lang/management/VMThreadInfo.java
diff -N vm/reference/java/lang/management/VMThreadInfo.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ vm/reference/java/lang/management/VMThreadInfo.java 26 Jun 2006 20:44:22
-0000
@@ -0,0 +1,159 @@
+/* VMThreadInfo.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;
+
+/**
+ * Provides low-level information about a thread.
+ *
+ * @author Andrew John Hughes ([EMAIL PROTECTED])
+ * @since 1.5
+ * @see java.lang.management.ThreadInfo
+ */
+final class VMThreadInfo
+{
+
+ /**
+ * Return the number of times the specified thread
+ * has been in the [EMAIL PROTECTED] java.lang.Thread.State#BLOCKED}
+ * state.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the number of times the thread has been blocked.
+ */
+ static native long getBlockedCount(Thread thread);
+
+ /**
+ * Returns the accumulated number of milliseconds the
+ * specified thread has spent in the
+ * [EMAIL PROTECTED] java.lang.Thread.State#BLOCKED} state. This
+ * method is only called if thread contention monitoring
+ * is both supported and enabled.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the accumulated number of milliseconds the
+ * thread has been blocked for.
+ */
+ static native long getBlockedTime(Thread thread);
+
+ /**
+ * Returns the monitor lock the specified thread is
+ * waiting for. This is only called when the thread
+ * is in the [EMAIL PROTECTED] java.lang.Thread.State#BLOCKED}
+ * state.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the monitor lock the thread is waiting for.
+ */
+ static native Object getLock(Thread thread);
+
+ /**
+ * Returns the thread which currently owns the monitor
+ * lock the specified thread is waiting for. This is
+ * only called when the thread is in the
+ * [EMAIL PROTECTED] java.lang.Thread.State#BLOCKED} state. It
+ * may return <code>null</code> if the lock is not held
+ * by another thread.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the thread which owns the monitor lock the
+ * thread is waiting for, or <code>null</code>
+ * if it doesn't have an owner.
+ */
+ static native Thread getLockOwner(Thread thread);
+
+ /**
+ * Return the number of times the specified thread
+ * has been in the [EMAIL PROTECTED] java.lang.Thread.State#WAITING}
+ * or [EMAIL PROTECTED] java.lang.Thread.State#TIMED_WAITING} states.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the number of times the thread has been in
+ * waiting state.
+ */
+ static native long getWaitedCount(Thread thread);
+
+ /**
+ * Returns the accumulated number of milliseconds the
+ * specified thread has spent in either the
+ * [EMAIL PROTECTED] java.lang.Thread.State#WAITING} or
+ * [EMAIL PROTECTED] java.lang.Thread.State#TIMED_WAITING} states.
+ * This method is only called if thread contention
+ * monitoring is both supported and enabled.
+ *
+ * @param thread the thread to return statistics on.
+ * @return the accumulated number of milliseconds the
+ * thread has been in a waiting state for.
+ */
+ static native long getWaitedTime(Thread thread);
+
+ /**
+ * Returns true if the specified thread is in a native
+ * method.
+ *
+ * @param thread the thread to return statistics on.
+ * @return true if the thread is in a native method, false
+ * otherwise.
+ */
+ static native boolean isInNative(Thread thread);
+
+ /**
+ * Returns true if the specified thread is suspended.
+ *
+ * @param thread the thread to return statistics on.
+ * @return true if the thread is suspended, false otherwise.
+ */
+ static native boolean isSuspended(Thread thread);
+
+ /**
+ * Returns a stack trace for the specified thread of
+ * the supplied depth. If the depth is
+ * <code>Integer.MAX_VALUE</code>, then the returned
+ * depth is equal to the full stack trace available.
+ * The depth will be greater than zero, due to
+ * filtering in methods prior to this call.
+ *
+ * @param thread the thread whose stack trace should
+ * be returned.
+ * @param maxDepth the maximum depth of the trace.
+ * This will be greater than zero.
+ * <code>Integer.MAX_VALUE</code>
+ * represents the full trace.
+ */
+ static native StackTraceElement[] getStackTrace(Thread thread,
+ int maxDepth);
+}
signature.asc
Description: Digital signature
