Author: kohsuke
Date: Sun Jul 31 21:41:08 2005
New Revision: 226738
URL: http://svn.apache.org/viewcvs?rev=226738&view=rev
Log:
added a half-written tutorial
Added:
jakarta/commons/sandbox/javaflow/trunk/xdocs/tutorial.xml
Added: jakarta/commons/sandbox/javaflow/trunk/xdocs/tutorial.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/sandbox/javaflow/trunk/xdocs/tutorial.xml?rev=226738&view=auto
==============================================================================
--- jakarta/commons/sandbox/javaflow/trunk/xdocs/tutorial.xml (added)
+++ jakarta/commons/sandbox/javaflow/trunk/xdocs/tutorial.xml Sun Jul 31
21:41:08 2005
@@ -0,0 +1,115 @@
+<?xml version="1.0"?>
+<document>
+ <properties>
+ <title>Tutorial</title>
+ <author email="commons-dev@jakarta.apache.org">Commons Documentation
Team</author>
+ <revision>$Id: downloads.xml 155451 2005-02-26 13:22:47Z dirkv $</revision>
+ </properties>
+ <body>
+ <section name="Tutorial">
+ <p>
+ This document shows the basic usage of the javaflow API.
+ </p>
+ <p>
+ First, consider the following program:
+ </p>
+<source>
+class MyRunnable implements Runnable, Continuable {
+ public void run() {
+ System.out.println("started!");
+ for( int i=0; i<10; i++ )
+ echo(i);
+ }
+ private void echo(int x) {
+ System.out.println(x);
+ Continuation.suspend();
+ }
+}
+
+Continuation c = Continuation.startWith(new MyRunnable());
+System.out.println("returned a continuation");
+</source>
+ <p>
+ When the <tt>startWith</tt> method is invoked, Javaflow
sets up the "environment", then invoke the run method of the object it
received. It's not very important for users to know what this environment is,
but that is what enables all the magics we'll see in this document.
+ </p>
+ <p>
+ As a result of this, you'll see the "started!" message
printed in the console. The thread then goes into a for loop, calls the echo
method, prints "0", then calss the <tt>Continuation.suspend()</tt>.
+ </p>
+ <p>
+ This is where an interesting thing happens. In this
method, the stack frames that are leading up to the Continuation.suspend() and
all local variables are captured into a <tt>Continuation</tt> object, and then
the execution resumes by returning from the <tt>startWith</tt> method (instead
of returning from the <tt>suspend</tt> method.) So the next message you'll see
on the console is "returned a continuation". This all happens by using just one
thread.
+ </p>
+ <p>
+ You can then do something else, and eventually you'll
do the following:
+ </p>
+<source>
+Continuation d = Continuation.continueWith(c);
+System.out.println("returned another continuation");
+</source>
+ <p>
+ When the <tt>continueWith</tt> method is invoked,
javaflow sets up the environment again, and restores stack frames and local
variables. Instead of returning from the <tt>continue</tt> method, the
execution resumes by returning from the <tt>suspend</tt> method that never
returned before.
+ </p>
+ <p>
+ Now what happens? The echo method returns, then you'll
go another iteration of the for loop. So the next message you'll see is "1".
Then, the <tt>suspend</tt> method is called again.
+ </p>
+ <p>
+ At this point, the stack frames and the local variables
are captured into a new <tt>Continuation</tt> object, and then the execution
resumes by returning from the <tt>continueWith</tt> method. So the next message
you'll see is "returned another continuation".
+ </p>
+ <p>
+ If you think of two threads, the execution flow so far
would be probably easier to understand, although with javaflow all of this
happens in one thread. We can repeatedly continue the returned
<tt>Continuation</tt> object so that it will print 2,3,...,9 as shown in the
following code:
+ </p>
+<source>
+while(d!=null) {
+ d = Continuation.continueWith(d);
+}
+</source>
+ <p>
+ Eventually, the for loop exits and the <tt>run</tt>
method returns. At that point, there's nothing left to execute. So the
<tt>continueWith</tt> method returns <tt>null</tt>.
+ </p>
+ </section>
+ <section name="Wait, But There's More!">
+ <p>
+ Now, so far the things we did can be easily done if you
are to use two threads. So let's do something more interesting. Remember the
'c' object we captured earlier? We've already continued it once, but we can do
it again:
+ </p>
+<source>
+Continuation.continueWith(c);
+</source>
+ <p>
+ This restores the stack frames and local variables
captured in 'c'. Then the execution resumes by returning from the
<tt>suspend</tt> method. When 'c' was captured, the value of 'i' was 0. So the
next number you'll see printed is "1". Then it executes <tt>suspend</tt>
method, then the execution returns from the <tt>continueWith</tt> method.
+ </p>
+ <p>
+ Isn't this interesting? In a way, we went back the time
and re-run the same code again. The <tt>continueWith</tt> method doesn't have
to be invoked from the same method.
+ </p>
+ <p>
+ A <tt>Continuation</tt> can be serialized if all
objects it captured is also serializable. In other words, all the local
variables (including all <tt>this</tt> objects) need to be marked as
<tt>Serializable</tt>. In this example, you need to mark the
<tt>MyRunnable</tt> class as <tt>Serializable</tt>. A serialized continuation
can be sent over to another machine or used later.
+ </p>
+ </section>
+ <section name="Preparation">
+ <p>
+ For these to work, javaflow needs to enhance the byte
code of your program that runs inside the continuation-enabled environment. The
<tt>Continuable</tt> interface is used to mark those classes. Javaflow uses
this marker interface to decide which class to instrument.
(<tt>Continuable</tt> classes can be still executed normally outside the
environment, but it runs somewhat slower.)
+ </p>
+ <p>
+ When the <tt>Continuation.suspend</tt> runs, all the
methods on the stack frames need to be on classes marked as
<tt>Continuable</tt>.
+ </p>
+ <p>
+ There are two ways to instrument bytecode. One way is
to do it statically. This means using the following Ant task as a part of your
build process:
+ </p>
+<source><![CDATA[
+<taskdef name="javaflow"
classname="org.apache.commons.javaflow.ant.AntRewriteTask">
+ <classpath>
+ ...
+ </classpath>
+</taskdef>
+
+<rewriteTask destdir="build/classes">
+ <fileset dir="build/classes" includes="**/*.class" />
+</rewriteTask>
+]]></source>
+ <p>
+ This scans the build/classes directory for any class
file that needs instrumentation. For more details about this Ant task, see <a
href="javascript:window.alert('todo')">this document</a>.
+ </p>
+ <p>
+ Alternatively, you can do this dynamically at runtime,
by using javaflow's custom class loader. *TODO*TODO*TODO*
+ </p>
+ </section>
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
