com.cloudbees.groovy.cps

Class Continuable

java.lang.Object

com.cloudbees.groovy.cps.Continuable

All Implemented Interfaces:

Serializable

public class Continuable
extends Object
implements Serializable

Mutable representation of the program. This is the primary API of the groovy-cps library to the outside.

Author:

Kohsuke Kawaguchi

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static StackTraceElement	SEPARATOR_STACK_ELEMENT The artificial StackTraceElement that appears in the stack trace when the CPS library fixes up the stack trace.

Constructor Summary

Constructors

Constructor and Description
Continuable(Block block) Creates a Continuable that executes the block of code in a fresh empty environment.
Continuable(Block block, Env e) Creates a Continuable that executes the block in the specified environment.
Continuable(Continuable src)
Continuable(Next n)
Continuable(groovy.lang.Script cpsTransformedScript) Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable.
Continuable(groovy.lang.Script cpsTransformedScript, Env env) Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable, in the context of the given Env.
Continuable(groovy.lang.Script cpsTransformedScript, Env env, Continuation k) Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable.

Method Summary

Methods

Modifier and Type	Method and Description
Continuable	fork() Creates a shallow copy of Continuable.
List<StackTraceElement>	getStackTrace() Returns the stack trace in the CPS-transformed code that indicates where this Continuable will resume from.
boolean	isResumable() Checks if this Continuable is pointing at the end of the program which cannot be resumed.
void	jump(Continuable c) Ignore whatever that we've been doing, and jumps the execution to the given continuation.
void	prepend(Continuable c, com.google.common.base.Function<Outcome,Outcome> mapper) Set aside what we are executing, and instead resume the next execution from the point the given 'Continuable' points to.
Object	run(Object arg) Starts/resumes this program until it suspends the next time.
Outcome	run0(Outcome cn) Resumes this program by either returning the value from suspend(Object) or throwing an exception
Object	runByThrow(Throwable arg)
void	superInterrupt(Throwable t) Sets a super-interrupt.
static Object	suspend(Object v) Called from within CPS transformed program to suspends the execution.

Methods inherited from class java.lang.Object

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

Field Detail

SEPARATOR_STACK_ELEMENT

public static final StackTraceElement SEPARATOR_STACK_ELEMENT

The artificial StackTraceElement that appears in the stack trace when the CPS library fixes up the stack trace. This separator separates the regular call stack that tracks the actual call stack JVM executes and the synthesized CPS call stack that CPS-transformed program is logically executing.

Constructor Detail

Continuable

public Continuable(Continuable src)

Continuable

public Continuable(Next n)

Continuable

public Continuable(Block block)

Creates a Continuable that executes the block of code in a fresh empty environment.

Continuable

public Continuable(Block block,
           Env e)

Creates a Continuable that executes the block in the specified environment.

Continuable

public Continuable(groovy.lang.Script cpsTransformedScript)

Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable.

Continuable

public Continuable(groovy.lang.Script cpsTransformedScript,
           Env env)

Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable, in the context of the given Env. The added 'env' parameter can be used to control the execution flow in case of exceptions, and/or providing custom Invoker

Continuable

public Continuable(groovy.lang.Script cpsTransformedScript,
           Env env,
           Continuation k)

Takes a Script compiled from CPS-transforming GroovyShell and wraps that into a Continuable. The added 'k' parameter can be used to pass the control to somewhere else when the script has finished executing.

Method Detail

fork

public Continuable fork()

Creates a shallow copy of Continuable. The copy shares all the local variables of the original Continuable, and point to the exact same point of the program.

run

public Object run(Object arg)
           throws InvocationTargetException

Starts/resumes this program until it suspends the next time.

Throws:

InvocationTargetException - if the program threw an exception that it didn't handle by itself.

runByThrow

public Object runByThrow(Throwable arg)
                  throws InvocationTargetException

Throws:

InvocationTargetException

run0

public Outcome run0(Outcome cn)

Resumes this program by either returning the value from suspend(Object) or throwing an exception

superInterrupt

public void superInterrupt(Throwable t)

Sets a super-interrupt.

A super interrupt works like Thread.interrupt() that throws InterruptedException. It lets other threads interrupt the execution of Continuable by making it throw an exception.

Unlike InterruptedException, which only gets thrown in specific known locations, such as Object.wait(), this "super interruption" gets thrown at any point in the execution, even during while(true) ; kind of loop.

The

isResumable

public boolean isResumable()

Checks if this Continuable is pointing at the end of the program which cannot be resumed.

suspend

public static Object suspend(Object v)

Called from within CPS transformed program to suspends the execution.

When this method is called, the control goes back to the caller of run(Object), which returns with the argument given to this method.

When the continuable is resumed via run(Object) later, the argument to the run method will become the return value from this method to the CPS-transformed program.

getStackTrace

public List<StackTraceElement> getStackTrace()

Returns the stack trace in the CPS-transformed code that indicates where this Continuable will resume from. If this object represents a yet-started program, an empty list will be returned.

jump

public void jump(Continuable c)

Ignore whatever that we've been doing, and jumps the execution to the given continuation.

Aside from the obvious use case of completely overwriting the state of Continuable, more interesting case is Sets aside the current continuation aside, schedule the evaluation of the given block in the given environment, then when done pass the result to the given Continuation. A common pattern is for that Continuation to then resume executing the current execution that was set aside.

 Continuable c = ...;

 final Continuable pausePoint = new Continuable(c); // set aside what we were doing
 c.jump(bodyOfNewThread,env,new Continuation() {
      public Next receive(Object o) {
          // o is the result of evaluating bodyOfNewThread (the failure will go to the handler specified by 'env')
          doSomethingWith(c);

          if (...) {// maybe you want to yield this value, then resume from the pause point?
              return Next.yield0(new Outcome(o,null),pausePoint);
          }
          if (...) {// maybe you want to keep going by immediately resuming from the pause point with 'o'
              return Next.go0(new Outcome(o,null),pausePoint);
          }

          // maybe you want to halt the execution by returning
          return Next.terminate0(new Outcome(o,null));
      }
 });

 c.run(...); // this will start executing from 'bodyOfNewThread'

 

prepend

public void prepend(Continuable c,
           com.google.common.base.Function<Outcome,Outcome> mapper)

Set aside what we are executing, and instead resume the next execution from the point the given 'Continuable' points to. But when that's done, instead of completing the computation, come back to executing what we set aside.