You are viewing a plain text version of this content. The canonical link for it is here.
Posted to kato-commits@incubator.apache.org by mo...@apache.org on 2009/07/22 17:38:41 UTC
svn commit: r796806 -
/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
Author: monteith
Date: Wed Jul 22 17:38:41 2009
New Revision: 796806
URL: http://svn.apache.org/viewvc?rev=796806&view=rev
Log:
Update JavaMonitor JavaDoc.
Modified:
incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java?rev=796806&r1=796805&r2=796806&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java (original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java Wed Jul 22 17:38:41 2009
@@ -23,31 +23,48 @@
/**
- * Represents the underlying monitor used by a Java Virtual Machine to manage locking and synchronization of a Java object,
+ * <p>Represents the underlying monitor used by a Java Virtual Machine to manage locking and synchronization of a Java object.</p>
*
- * <p>The underlying monitor is implementation specific.<p>
+ * <p>The underlying monitor is implementation specific. Some implementations may choose to use their monitor implementations to
+ * control access to Java Virtual Machine resources that are not objects. In such cases, {@link #getObject()} will return null.
+ * </p>
*
* <p>Java programmers use the synchronized modifier on methods and the synchronized block within methods to control simultaneous access to Java objects.
- * The synchronisation mechanism is typically implemented using a variety of techniques. The JavaMonitor does not distinquish between these types,
- * instead it represents a common simple abstraction that allows the caller to determine;
+ * Java uses monitors for this synchronization, which can be implemented using a variety of techniques. The JavaMonitor class presents
+ * the simple monitor abstraction that allows the caller to determine:
* <ul>
- * <li>which thread currently owns the monitor</li>
- * <li>which threads are waiting to be informed when the monitor is released</li>
- * <li>which threads are waiting to be woken after having</li>
+ * <li>Which thread currently owns the monitor</li>
+ * <li>Which threads are waiting to be woken after they have gotten ownship of the monitor and relinquished it, normally within
+ * Object.wait() within a synchronized block or method.</li>
+ * <li>The threads that waiting to get ownership of the monitor. These are typically threads waiting to enter a
+ * synchronized block or method.</li>
* </ul>
+ * </p>
+ *
+ * <p>This API presents only what exists at the Java Virtual Machine bytecode level. The locking facilities provided by the {@link java.util.concurrent.lock}
+ * package are expected to be implemented on top of ordinary Java monitors.</p>
*/
public interface JavaMonitor {
/**
- * Get the object associated with this monitor.
- * @return the object associated with this monitor, or null if this is a raw monitor or a valid object could not be retrieved.
+ * <p>Get the object associated with this monitor. Not all JavaMonitors will have objects, as there may be JavaMonitors that
+ * are used to control access to internal Java Virtual Machine resources ("Raw" monitors).
+ * </p>
+ *
+ * @return the Java object associated with this monitor, or null.
*/
JavaObject getObject();
/**
- * Note that the name of a JavaMonitor is not necessarily meaningful but is provided here as it is
- * usually present in the running VM. If there is no name for the monitor a synthetic name will be
- * created by Kato.
+ * <p>Get the name of a monitor.</p>
+ *
+ * <p>For monitors not associated with object ("raw" monitors), it is expected that this method will return
+ * a descriptive name that is meaningful to the Java Virtual Machine implementation. For example "Heap lock" might
+ * be a monitor controlling exclusive access to the Java heap.</p>
+ *
+ * <p>For objects, the expectation is that the name will uniquely identify the object the monitor is associated with.
+ * This is not expected to necessarily be consistent between different dumps of the same JVM.
+ * </p>
*
* @return the name of the monitor (never null)
* @throws CorruptDataException
@@ -55,15 +72,17 @@
String getName() throws CorruptDataException;
/**
- * Get the thread which currently owns the monitor
- * @return the owner of the monitor, or null if the monitor is unowned
+ * <p>Get the thread which currently owns the monitor. This may be null if the monitor is not owned.
+ * </p>
+ *
+ * @return the owner of the monitor, or null if the monitor is not owned
* @throws CorruptDataException
*/
JavaThread getOwner() throws CorruptDataException;
/**
- * <p>Get the set of threads waiting to enter the monitor.
- *
+ * <p>Get the set of threads waiting to enter the monitor.
+ * </p>
* <p>The returned list follows the standard semantics for javax.tools.diagnostics collections.</p>
* <p>The returned value is never null but can be an empty list.</p>
@@ -75,9 +94,11 @@
List<JavaThread> getEnterWaiters();
/**
- * Get the set of threads waiting to be notified on the monitor (in the Object.wait method)
+ * <p>Get the set of threads waiting to be notified on the monitor.
+ * They are usually threads in the {@link java.lang.Object#wait()} method.</p>
* <p>The returned list follows the standard semantics for javax.tools.diagnostics collections.</p>
* <p>The returned value is never null but can be an empty list.</p>
+ *
* @return a list of threads waiting to be notified on this monitor.
*
* @see JavaThread
@@ -86,7 +107,8 @@
List<JavaThread> getNotifyWaiters();
/**
- * Get the identifier for this monitor
+ * <p>Get the identifier for this monitor.</p>
+ *
* @return The pointer which uniquely identifies this monitor in memory.
*/
ImagePointer getID();