User Guide - Part Three

I was out for this weekend and will be busy the next few days, but today I'll talk about continuations. I really don't think I'm up to the task of explaining continuations, however this is a good introduction on the topic.

So, what will continuations be like? In the JauVM a Continuation is Java object, that represents a snapshot of the execution state of an Interpreter object, including the values of local variables. Here is its implementation:

Continuation.java

package net.sf.jauvm;

import java.io.Serializable;

public class Continuation implements Serializable {
    public Continuation() {
        throw new UnsupportedOperationException();
    }

    public void returnTo() {
        throw new UnsupportedOperationException();
    }

    public void returnTo(Object o) {
        throw new UnsupportedOperationException();
    }

    public void throwTo(Throwable t) {
        throw new UnsupportedOperationException();
    }

    protected void continueFrom() {
        throw new UnsupportedOperationException();
    }
}

The first thing to note are the methods' implementations. All those operations are unsupported because you're not supposed to use them in your regular Java code. A Continuation is a special object, recognized by JauVM's Interpreter, and whose implementation is closely tied to it. A continuation can not be reified or invoked in code ran by the regular JVM.

To capture a continuation, you have to create a new Continuation object. For example:

@interpretable void aMethod() {
    Continuation cont = new Continuation();
}

In the above code, the variable cont represents the execution state of the current caller of aMethod.

Since cont is a regular Java object you can return it, store it in a variable, assign it to a field of another object - whatever you like. You can also call any of it's instance methods, namely the overloaded returnTo method. When you make such a call, the current execution state of the program is discarded and the snapshot of the program represented by the Continuation object is resumed in its place. You may also pass an argument to that method call, which becomes the return value of the method in which the Continuation was captured. For instance:

@interpretable Object aMethod() {
    return new Continuation();
}

@interpretable void anotherMethod() {
    Object obj = aMethod();

    if (obj instanceof Continuation) {
        System.out.println("obj is a continuation");
        Continuation cont = (Continuation) obj;
        cont.returnTo(100);
    }
    
    System.out.println("obj is " + obj.toString());
}

Invoking anotherMethod yields the following output:

obj is a Continuation
obj is 100

When returnTo is invoked, the program jumps back to the call to aMethod, but this time aMethod returns the Integer 100 passed into returnTo.

What about throwTo? A continuation can be thought as representing the return from a method invocation. In Java, in addition to a normal return, a method may return due to an exception. The throwTo method throws its argument in the context of the Continuation after it's restored. For example:

@interpretable Object aMethod() {
    return new Continuation();
}

@interpretable void anotherMethod() {
    Object obj = null;

    try {
        obj = aMethod();
    } catch (RuntimeException e) {
        System.out.println(e);
    }

    if (obj instanceof Continuation) {
        System.out.println("obj is a Continuation");
        Continuation cont = (Continuation) obj;
        cont.throwTo(new RuntimeException("thrown from aMethod"));
    }
}

Invoking anotherMethod yields the following output:

obj is a Continuation
RuntimeException: thrown from aMethod

This isn't all there is to know about continuations, but this post is already huge, the rest will have to wait. Keep tuned!