org.apache.commons.javaflow
Class Continuation

java.lang.Object
  org.apache.commons.javaflow.Continuation

All Implemented Interfaces:

java.io.Serializable

public final class Continuation
extends java.lang.Object
implements java.io.Serializable

Snapshot of a thread execution state.

A Continuation object is an immutable object that captures everything in the Java stack. This includes (1) current instruction pointer, (2) return addresses, and (3) local variables.

Continuation objects are used to restore the captured execution states later.

Version:

CVS $Revision: 480487 $

Author:

Stephan Michels, Torsten Curdt

See Also:

Serialized Form

Method Summary

static void	again() Jumps to where the execution was resumed.
static void	cancel() Jumps to where the execution was resumed, and suspend execution.
static Continuation	continueWith(Continuation pOldContinuation) Resumes the execution of the specified continuation from where it's left off.
static Continuation	continueWith(Continuation pOldContinuation, java.lang.Object pContext) Resumes the execution of the specified continuation from where it's left off and creates a new continuation representing the new state.
static void	exit() Completes the execution of the running continuation.
static java.lang.Object	getContext() get the current context.
boolean	isSerializable()
static Continuation	startSuspendedWith(java.lang.Runnable pTarget) Creates a new Continuation object from the specified Runnable object.
static Continuation	startWith(java.lang.Runnable pTarget) Starts executing the specified Runnable object in an environment that allows suspend().
static Continuation	startWith(java.lang.Runnable pTarget, java.lang.Object pContext) Starts executing the specified Runnable object in an environment that allows suspend().
static void	suspend() Stops the running continuation.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getContext

public static java.lang.Object getContext()

get the current context.

This method returns the same context object given to startWith(Runnable, Object) or continueWith(Continuation, Object).

A different context can be used for each run of a continuation, so this mechanism can be used to associate some state with each execution.

Returns:

null if this method is invoked outside startWith(Runnable, Object) or continueWith(Continuation, Object) .

startSuspendedWith

public static Continuation startSuspendedWith(java.lang.Runnable pTarget)

Creates a new Continuation object from the specified Runnable object.

Unlike the startWith(Runnable) method, this method doesn't actually execute the Runnable object. It will be executed when it's continued.

Returns:

always return a non-null valid object.

startWith

public static Continuation startWith(java.lang.Runnable pTarget)

Starts executing the specified Runnable object in an environment that allows suspend().

This is a short hand for startWith(target,null).

See Also:

startWith(Runnable, Object).

startWith

public static Continuation startWith(java.lang.Runnable pTarget,
                                     java.lang.Object pContext)

Starts executing the specified Runnable object in an environment that allows suspend(). This method blocks until the continuation suspends or completes.

Parameters:

pTarget - The object whose run method will be executed.

pContext - This value can be obtained from getContext() until this method returns. Can be null.

Returns:

If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.

See Also:

getContext()

continueWith

public static Continuation continueWith(Continuation pOldContinuation)

Resumes the execution of the specified continuation from where it's left off.

This is a short hand for continueWith(resumed,null).

See Also:

continueWith(Continuation, Object)

continueWith

public static Continuation continueWith(Continuation pOldContinuation,
                                        java.lang.Object pContext)

Resumes the execution of the specified continuation from where it's left off and creates a new continuation representing the new state. This method blocks until the continuation suspends or completes.

Parameters:

pOldContinuation - The resumed continuation to be executed. Must not be null.

pContext - This value can be obtained from getContext() until this method returns. Can be null.

Returns:

If the execution completes and there's nothing more to continue, return null. Otherwise, the execution has been suspended, in which case a new non-null continuation is returned.

See Also:

getContext()

isSerializable

public boolean isSerializable()

suspend

public static void suspend()

Stops the running continuation.

This method can be only called inside continueWith(org.apache.commons.javaflow.Continuation) or startWith(java.lang.Runnable) methods. When called, the thread returns from the above methods with a new Continuation object that captures the thread state.

Throws:

java.lang.IllegalStateException - if this method is called outside the continueWith(org.apache.commons.javaflow.Continuation) or startWith(java.lang.Runnable) methods.

exit

public static void exit()

Completes the execution of the running continuation.

This method can be only called inside continueWith(org.apache.commons.javaflow.Continuation) or startWith(java.lang.Runnable) methods. When called, the thread returns from the above methods with null, indicating that there's nothing more to continue.

This method is similiar to how System.exit(int) works for JVM.

again

public static void again()

Jumps to where the execution was resumed.

This method can be only called inside continueWith(org.apache.commons.javaflow.Continuation) or startWith(java.lang.Runnable) methods. When called, the execution jumps to where it was resumed (if the execution has never resumed before, from the beginning of Runnable.run().)

Consider the following example:

 Continuation.suspend();
 System.out.println("resumed");

 r = new Random().nextInt(5);
 if(r!=0) {
   System.out.println("do it again");
   Continuation.again();
 }

 System.out.println("done");
 

This program produces an output like this (the exact number of 'do it again' depends on each execution, as it's random.)

 resumed
 do it again
 resumed
 do it again
 resumed
 do it again
 resumed
 done
 

The calling startWith(Runnable) method and continueWith(Continuation) method does not return when a program running inside uses this method.

cancel

public static void cancel()

Jumps to where the execution was resumed, and suspend execution.

This method almost works like the again() method, but instead of re-executing, this method first suspends the execution.

Therefore, the calling startWith(Runnable) method and continueWith(Continuation) method return when a program running inside uses this method.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object