Class ContinuationResult

java.lang.Object
com.oracle.truffle.api.bytecode.ContinuationResult
All Implemented Interfaces:
TruffleObject
public final class ContinuationResult extends Object implements TruffleObject
Representation of a continuation closure, consisting of a resumable RootNode, the interpreter state, and a yielded result. A ContinuationResult is returned when the interpreter yields. It can later be resumed to continue execution. It can be resumed only once.

Below illustrates an example usage of ContinuationResult. 

// Assume yieldingRootNode implements the following pseudocode:
//
// fun f(x):
//   y = yield (x + 1)
//   return x + y
//
MyBytecodeRootNode yieldingRootNode = ...;

// The result is a ContinuationResult
ContinuationResult yielded = (ContinuationResult) yieldingRootNode.getCallTarget().call(42);
assert yielded.getResult() == 43;

// Resume the continuation using continueWith. Pass 58 as the value for yield.
Integer returned = (Integer) yielded.continueWith(58);
assert returned == 100;
For performance reasons, a language may wish to define an inline cache over continuations. In such a case, they should not call continueWith(Object), but instead cache and call the root node or call target directly. This is necessary because continuation results are dynamic values, not partial evaluation constants. Be careful to conform to the calling convention when calling the continuation root node directly.
Since:
24.2
See Also:

  • Constructor Details

    • ContinuationResult

      public ContinuationResult(ContinuationRootNode rootNode, MaterializedFrame frame, Object result)
      Creates a continuation.

      The generated interpreter will use this constructor. Continuations should not be created directly by user code.

      Since:
      24.2

  • Method Details

    • continueWith

      public Object continueWith(Object value)
      Resumes the continuation.

      This method should generally not be used on compiled code paths. Each yield produces a unique ContinuationResult, so the receiver object cannot be easily cached, which means partial evaluation will be unable to resolve the call target. Instead, it is recommended to cache the continuation call target and call it directly.

      Parameters:
      value - the value produced by the yield operation in the resumed execution.
      Since:
      24.2

    • getContinuationRootNode

      public ContinuationRootNode getContinuationRootNode()
      Returns the root node that resumes execution.

      Note that the continuation root node has a specific calling convention. See getContinuationCallTarget() for more details, or invoke the root node directly using continueWith(Object).

      Since:
      24.2
      See Also:

    • getContinuationCallTarget

      public RootCallTarget getContinuationCallTarget()
      Returns the call target for the continuation root node. The call target can be invoked to resume the continuation. It is recommended to register this call target in an inline cache and call it directly.

      The call target takes two parameters: the materialized interpreter frame and an Object value to resume execution with. The value becomes the value produced by the yield operation in the resumed execution.

      Since:
      24.2

    • getFrame

      public MaterializedFrame getFrame()
      Returns the state of the interpreter at the point that it was suspended.
      Since:
      24.2

    • getResult

      public Object getResult()
      Returns the value yielded by the yield operation.
      Since:
      24.2

    • getBytecodeLocation

      public BytecodeLocation getBytecodeLocation()
      Returns the location at which the continuation was created.

      This location can have a different BytecodeNode from the source root node if the source bytecode was updated (explicitly or implicitly).

      Since:
      24.2

    • toString

      public String toString()
      Returns a string representation of a ContinuationResult.
      Overrides:
      toString in class Object
      Since:
      24.2