incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r796806 - /incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
Date Wed, 22 Jul 2009 17:38:41 GMT
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();



Mime
View raw message