incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r805473 - in /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters: API.xml examples.xml
Date Tue, 18 Aug 2009 16:02:37 GMT
Author: monteith
Date: Tue Aug 18 16:02:37 2009
New Revision: 805473

URL: http://svn.apache.org/viewvc?rev=805473&view=rev
Log:
Split out examples from API.xml. Add two examples.

Added:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml   (with
props)
Modified:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml?rev=805473&r1=805472&r2=805473&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml Tue Aug 18
16:02:37 2009
@@ -138,9 +138,5 @@
 	</sect1>
 
 	<xi:include href="principles.xml" />
-	
-		
-	<sect1 xml:id="api.examples">
-		<title>Examples</title>
-	</sect1>
+	<xi:include href="examples.xml" />
 </chapter>

Added: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml?rev=805473&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (added)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml Tue Aug
18 16:02:37 2009
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sect1 xml:id="api.examples" version="5.0" 
+         xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:svg="http://www.w3.org/2000/svg"
+         xmlns:mml="http://www.w3.org/1998/Math/MathML"
+         xmlns:html="http://www.w3.org/1999/xhtml"
+         xmlns:db="http://docbook.org/ns/docbook">
+	<title>Examples</title>
+	<sect2 xml:id="api.examples.intro">
+	<title>Introduction</title>
+	<para>
+	This section contains annotated examples to demonstrate some simple tasks and show how the
API
+	should be called.	
+	</para>
+	</sect2>
+	
+	<sect2 xml:id="api.examples.open">
+	<title>Opening Images</title>
+	<para><classname>Image</classname> instances are obtained using the <classname>javax.tools.diagnostics.FactoryRegistry</classname>
class.
+	</para>
+	<para>
+	Programs using the API can obtain an Image like so:
+	
+	<example xml:id="api.examples.open.getimage">	
+	<title>Opening an Image</title>
+	<programlisting>
+	<![CDATA[
+		Image image = FactoryRegistry.getDefaultRegistry().
+										getImage(new File("example.file"));
+	]]>	
+	</programlisting>
+	</example>
+	
+	</para>
+	
+	<para>
+	<classname>FactoryRegistry</classname> uses
+	<link xlink:href="http://java.sun.com/javase/6/docs/api/javax/imageio/spi/ServiceRegistry.html">javax.imageio.spi.ServiceRegistry</link>
+	as a registry of all API implementations known to the JVM. 
+	Implementors should ensure that <classname>FactoryRegistry</classname> is able
to see their 
+	<classname>ImageFactory</classname> by placing their implementation in a jar
file that contains a file
+	called <filename>META-INF/org.apache.kato.ImageFactory</filename> that contains
a line of text that is 
+	the name of the ImageFactory implementation, such as 
+	<programlisting>javax.tools.diagnostics.hprof.image.ImageFactoryImpl</programlisting>
+	</para>
+	</sect2>
+	
+	<sect2 xml:id="api.examples.cause">
+	<title>Determining Snapshot Cause</title>
+	<para>
+	Snapshots can be generated for a variety of reasons. The API can report	when a snapshot
is generated when the 
+	JVM receives a POSIX type signal, whether that be synchronous or asynchronous.
+	For example, if a JNI library causes a <code>SIGSEGV</code> when running, this
might be detectable
+	through the API. In most cases, it should be possible through <methodname>ImageAddressSpace.getCurrentProcess()</methodname>
+	and <methodname>ImageProcess.getCurrentThread()</methodname> to determine which
process and which thread caused
+	the snapshot. 
+	</para>
+	
+	<para>
+	If a snapshot was generated for a reason other than a POSIX signal being received, then
the reason
+	has to be derived through knowledge of the JVM implementation. For example, if an option
was passed to
+	the JVM to generate a snapshot on entry to a particular method, all of the stack traces
could be searched
+	to determine if that method was present, and therefore probably causing the snapshot.
+	</para>
+	
+	<para>
+	Here is an example of how to determine the cause of a snapshot. 
+	</para>
+	<para>
+	First of all, there are the declarations. This implements a method in an interface that
expects
+	to simply be passed an <classname>Image</classname>. 
+<example xml:id="api.examples.cause.class">
+<title>CauseAnalyzer Class declaration</title>
+<programlisting>
+<![CDATA[
+package org.apache.kato.examples;
+
+import javax.tools.diagnostics.image.CorruptDataException;
+import javax.tools.diagnostics.image.DataUnavailable;
+import javax.tools.diagnostics.image.Image;
+import javax.tools.diagnostics.image.ImageAddressSpace;
+import javax.tools.diagnostics.image.ImageProcess;
+import javax.tools.diagnostics.image.ImageStackFrame;
+import javax.tools.diagnostics.image.ImageThread;
+import javax.tools.diagnostics.runtime.ManagedRuntime;
+import javax.tools.diagnostics.runtime.java.JavaRuntime;
+import javax.tools.diagnostics.runtime.java.JavaStackFrame;
+import javax.tools.diagnostics.runtime.java.JavaThread;
+
+/**
+ * This analyzer determines what process and thread
+ * caused the snapshot, and what signal, if any.
+ *
+ */
+public class CauseAnalyzer implements ImageAnalyzer {
+
+	@Override
+	public void analyze(Image image) {
+]]>
+</programlisting>
+</example>
+Next, the containing <classname>ImageAddressSpace</classname> instances are searched
for a current process.
+It is probable that there will be one address space and one process. Note the use of <code>for</code>.
+<example xml:id="api.examples.cause.cuurentprocess">
+<title>Find Current Process</title>
+<programlisting>
+<![CDATA[
+
+		for (ImageAddressSpace as : image.getAddressSpaces()) {
+			ImageProcess process = as.getCurrentProcess();
+			
+			// Only invoked if there is a "current" process,
+			// This is a process that caused the snapshot to occur.
+			if (process != null) {
+				try {
+]]>
+</programlisting>
+</example>
+
+Once found, the process can be queried for signal information and thread information.
+If a signal was raised, <methodname>ImageProcess.getSignalName()</methodname>
will not be null.
+The example reports this to the user, along with the number.
+
+<example xml:id="api.examples.cause.signalinfo">
+<title>Reporting signal information</title>
+<programlisting>
+<![CDATA[				
+					int signum = process.getSignalNumber();
+					String signame = process.getSignalName();
+
+					// Identify the process by number and command line.
+					System.out.println("Process "+process.getID()+
+							" was started with `" + 
+							process.getCommandLine()+"'");
+					
+					// The signals that cause the snapshot to be generated
+					if (signame != null) {
+						System.out.println("Snapshot caused by signal " + signame+"("+signum+")");						
+					}
+]]>
+</programlisting>
+</example>
+
+The program determines which thread caused the snapshot to be generated.
+If one is found, the thread is identified by ID and its properties (implementation dependent).
+
+<example xml:id="api.examples.cause.threadid">
+<title>Thread identification</title>
+<programlisting>
+<![CDATA[				
+					ImageThread thread = process.getCurrentThread();
+					// Identify the thread, by id, various properties and a stack trace.
+					if (thread != null) {
+						System.out.println("\nSnapshot caused by thread "+
+								thread.getID()+
+								", "+thread.getProperties());
+]]>
+</programlisting>
+</example>
+
+Next, the thread's stack frames are printed out. The example relies on
+<methodname>java.lang.Object.toString()</methodname> being implemented correctly.
							
+
+<example xml:id="api.examples.cause.stacktrace">
+<title>ImageThread stack trace</title>
+<programlisting>
+<![CDATA[				
+								
+						for(ImageStackFrame frame: thread.getStackFrames()) {
+							System.out.println("\t" + frame);
+						}
+]]>
+</programlisting>
+</example>
+
+This section of code relies on the relationship between <classname>JavaThread</classname>
instances
+and <classname>ImageThread</classname> instances to determine which Java thread
caused the snapshot.
+As the relationship is one-way, from Java to Image, all of the <classname>JavaThread</classname>
instances
+have to be queried. As <methodname>JavaThread.getImageThread()</methodname> might
be <code>null</code>,
+<methodname>java.lang.Object.equals</methodname> is executed against the <classname>ImageThread</classname>
+which we know to be not null. 
+
+<example xml:id="api.examples.cause.imagejavathread">
+<title>JavaThread/ImageThread correlation</title>
+<programlisting>
+<![CDATA[										
+						// Find JavaThread and then do stacktrace.
+RUNTIME:				for(ManagedRuntime runtime : process.getRuntimes() ) {
+							if (runtime instanceof JavaRuntime) {
+								JavaRuntime jr = (JavaRuntime) runtime;
+								
+								for(JavaThread jthread : jr.getThreads()) {
+									if (thread.equals(jthread.getImageThread())) {										
+										System.out.println("\nSnapshot caused by JavaThread "+
+												jthread.getName());
+										
+										for(JavaStackFrame frame : jthread.getStackFrames()) {
+											System.out.println("\t" + frame);
+										}
+										break RUNTIME;
+									}
+								}
+							}
+						}
+					}
+]]>
+</programlisting>
+</example>
+Here is the end of the definition of the class. In order to reduce the size of the example,
+the exceptions are handled outside of the API calls.
+<example xml:id="api.examples.cause.exceptions">
+<title>Exceptions</title>
+<programlisting>
+<![CDATA[																				
+				} catch (DataUnavailable e) {					
+					e.printStackTrace();
+				} catch (CorruptDataException e) {
+					e.printStackTrace();
+				}			
+			}
+		}
+	}
+}
+
+]]>
+</programlisting>
+</example>
+	
+	</para>
+	</sect2>
+</sect1>
\ No newline at end of file

Propchange: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message