Package org.apache.commons.javaflow.api

Class Continuation

java.lang.Object

org.apache.commons.javaflow.api.Continuation

All Implemented Interfaces:

Serializable

public abstract class Continuation
extends Object
implements 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.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method	Description
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 continuation)	Deprecated.
static Continuation	continueWith(Continuation continuation, Object value)	Deprecated.
static void	exit()	Completes the execution of the running continuation.
static Object	getContext()	get the current context.
boolean	isSerializable()	Check if captured continuation is serializable
abstract Continuation	multiShot()	View this continuation as a "multi-shot" continuation that may be resumed multiple times.
Continuation	resume()	Resumes the execution of the specified continuation from where it's left off.
Continuation	resume(Object value)	Resumes the execution of the specified continuation from where it's left off and creates a new continuation representing the new state.
protected abstract Continuation	resumeWith(ResumeParameter param)
abstract Continuation	singleShot()	View this continuation as a performance-optimized continuation that may be resumed only once.
static Continuation	startSuspendedWith(Runnable target)	Creates a new Continuation object from the specified Runnable object.
static Continuation	startSuspendedWith(Runnable target, boolean singleShot)	Creates a new Continuation object from the specified Runnable object.
static Continuation	startWith(Runnable target)	Starts executing the specified Runnable object in an environment that allows suspend().
static Continuation	startWith(Runnable target, boolean singleShot)	Starts executing the specified Runnable object in an environment that allows suspend().
static Continuation	startWith(Runnable target, Object context)	Starts executing the specified Runnable object in an environment that allows suspend().
static Continuation	startWith(Runnable target, Object context, boolean singleShot)	Starts executing the specified Runnable object in an environment that allows suspend().
static Object	suspend()	Stops the running continuation.
static Object	suspend(Object value)	Stops the running continuation.
void	terminate()	Abnormally terminates the suspended call chain represented by this continuation.
String	toString()
Object	value()	Accessor for value yielded by continuation

Methods inherited from class java.lang.Object

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

Method Detail

getContext

public static Object getContext()

get the current context.

This method returns the same context object given to startWith(Runnable, Object) or resume(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:

Currently associated continuation context

Throws:

NullPointerException - if this method is invoked outside startWith(Runnable, Object) or resume(Object) .

startSuspendedWith

public static Continuation startSuspendedWith(Runnable target)

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 resumed.

Parameters:

target - The object whose run method will be executed.

Returns:

always return a non-null valid object.

startSuspendedWith

public static Continuation startSuspendedWith(Runnable target,
                                              boolean singleShot)

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 resumed.

Parameters:

target - The object whose run method will be executed.

singleShot - If true then continuation constructed is performance-optimized but may be resumed only once. Otherwise "multi-shot" continuation is created that may be resumed multiple times.

Returns:

always return a non-null valid object.

startWith

public static Continuation startWith(Runnable target)

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

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

Parameters:

target - The object whose run method will be executed.

Returns:

Continuation object if runnable supplied is supended, otherwise null

See Also:

startWith(Runnable, Object)

startWith

public static Continuation startWith(Runnable target,
                                     boolean singleShot)

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

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

Parameters:

target - The object whose run method will be executed.

singleShot - If true then continuation constructed is performance-optimized but may be resumed only once. Otherwise "multi-shot" continuation is created that may be resumed multiple times.

Returns:

Continuation object if runnable supplied is supended, otherwise null

See Also:

startWith(Runnable, Object)

startWith

public static Continuation startWith(Runnable target,
                                     Object context)

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

Parameters:

target - The object whose run method will be executed.

context - 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()

startWith

public static Continuation startWith(Runnable target,
                                     Object context,
                                     boolean singleShot)

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

Parameters:

target - The object whose run method will be executed.

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

singleShot - If true then continuation constructed is performance-optimized but may be resumed only once. Otherwise "multi-shot" continuation is created that may be resumed multiple times.

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 continuation)

Deprecated.

This method is deprecated, please use resume() instead Resumes the execution of the specified continuation from where it's left off.

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

Parameters:

continuation - The suspended continuation to be resumed. Must not 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:

continueWith(Continuation, Object)

continueWith

public static Continuation continueWith(Continuation continuation,
                                        Object value)

Deprecated.

This method is deprecated, please use resume(Object) instead 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:

continuation - The suspended continuation to be resumed. Must not be null.

value - The value to be returned as a result form Continuation.suspend() call or 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(), suspend()

resume

public Continuation resume()

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

This is a short hand for resume(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:

resume(Object)

resume

public Continuation resume(Object value)

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:

value - The value to be returned as a result form Continuation.suspend() call or 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(), suspend()

terminate

public void terminate()

Abnormally terminates the suspended call chain represented by this continuation.

Use this method to execute any clean-up code of suspended methods (finally blocks) when there is no need to resume() the continuation.

isSerializable

public boolean isSerializable()

Check if captured continuation is serializable

Returns:

true if all variables on captured stack and runnable supplied are serializeble, false otherwise.

value

public Object value()

Accessor for value yielded by continuation

Returns:

The latest value yielded by suspended continuation. The value is passed from the continuation to the client code via suspend(Object)

multiShot

public abstract Continuation multiShot()

View this continuation as a "multi-shot" continuation that may be resumed multiple times.

Conversion to the multi-shot continuation is not always possible, i.e. already resumed single-shot continuation may not be converted to the multi-shot variant.

Returns:

self if this is already a multi-shot continuation or a newly constructed multi-shot continuation

singleShot

public abstract Continuation singleShot()

View this continuation as a performance-optimized continuation that may be resumed only once.

Conversion to the single-shot continuation is always possible

Returns:

self if this is already a single-shot continuation or a newly constructed single-shot continuation

suspend

public static Object suspend()

Stops the running continuation.

This method can be only called inside resume() 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.

Returns:

The value to be returned to suspended code after continuation is resumed. The value is passed from the client code via resume(Object) and is identical to value returned by getContext().

Throws:

IllegalStateException - if this method is called outside the resume() or startWith(java.lang.Runnable) methods.

suspend

public static Object suspend(Object value)

Stops the running continuation.

This method can be only called inside continueWith(org.apache.commons.javaflow.api.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 and with value() equals to parameter passed.

Parameters:

value - The intermediate result yielded by suspended continuations The value may be accessed via value() method of continuation returned

Returns:

The value to be returned to suspended code after continuation is resumed. The value is passed from the client code via @link #continueWith(Continuation, Object) and is identical to value returned by getContext().

Throws:

IllegalStateException - if this method is called outside the continueWith(org.apache.commons.javaflow.api.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.api.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.api.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 String toString()

Overrides:

toString in class Object

resumeWith

protected abstract Continuation resumeWith(ResumeParameter param)