Package com.oracle.truffle.api.bytecode

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(java.lang.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.
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 in user code.

      Since:
      24.2

  • Method Details

    • continueWith

      public Object continueWith(Object value)
      Resumes the continuation.
      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(java.lang.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.

      Languages can invoke this call target directly via continueWith(java.lang.Object). However, they may instead choose to access and call this call target directly (e.g., to register it in an inline cache).

      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