Package com.oracle.truffle.api

Interface TruffleRuntime

public interface TruffleRuntime
Interface representing a Truffle runtime object. The runtime is responsible for creating call targets and performing optimizations for them.
Since:
0.8 or earlier

  • Method Details

    • getName

      String getName()
      Name describing this runtime implementation for debugging purposes.
      Returns:
      the name as a String
      Since:
      0.8 or earlier

    • createDirectCallNode

      default DirectCallNode createDirectCallNode(CallTarget target)
      Creates a new runtime specific version of DirectCallNode.
      Parameters:
      target - the direct CallTarget to call
      Returns:
      the new call node
      Since:
      0.8 or earlier

    • createLoopNode

      LoopNode createLoopNode(RepeatingNode body)
      Creates a new loop node with an implementation provided by a Truffle runtime implementation. Using Truffle loop nodes allows the runtime to do additional optimizations such as on stack replacement for loops.
      Since:
      0.8 or earlier
      See Also:

    • createIndirectCallNode

      default IndirectCallNode createIndirectCallNode()
      Creates a new runtime specific version of IndirectCallNode.
      Returns:
      the new call node
      Since:
      0.8 or earlier

    • createAssumption

      Assumption createAssumption()
      Creates a new assumption object that can be checked and invalidated.
      Returns:
      the newly created assumption object
      Since:
      0.8 or earlier

    • createAssumption

      Assumption createAssumption(String name)
      Creates a new assumption object with a given name that can be checked and invalidated.
      Parameters:
      name - the name for the new assumption
      Returns:
      the newly created assumption object
      Since:
      0.8 or earlier

    • createVirtualFrame

      VirtualFrame createVirtualFrame(Object[] arguments, FrameDescriptor frameDescriptor)
      Creates a new virtual frame object that can be used to store values and is potentially optimizable by the runtime.
      Returns:
      the newly created virtual frame object
      Since:
      0.8 or earlier

    • createMaterializedFrame

      MaterializedFrame createMaterializedFrame(Object[] arguments)
      Creates a new materialized frame object that can be used to store values.
      Returns:
      the newly created materialized frame object
      Since:
      0.8 or earlier

    • createMaterializedFrame

      MaterializedFrame createMaterializedFrame(Object[] arguments, FrameDescriptor frameDescriptor)
      Creates a new materialized frame object with the given frame descriptor that can be used to store values.
      Parameters:
      frameDescriptor - the frame descriptor describing this frame's values
      Returns:
      the newly created materialized frame object
      Since:
      0.8 or earlier

    • iterateFrames

      default <T> T iterateFrames(FrameInstanceVisitor<T> visitor)
      Accesses the current stack, i.e., the contents of the Frames and the associated CallTargets. Iteration starts at the current frame. Iteration continues as long as FrameInstanceVisitor.visitFrame(com.oracle.truffle.api.frame.FrameInstance), which is invoked for every FrameInstance, returns null. Any non-null result of the visitor indicates that frame iteration should stop.

      Instances of FrameInstance must not escape the invocation of FrameInstanceVisitor.visitFrame(FrameInstance). This rule is currently not enforced, but will be in future versions of Truffle.

      Note that this method can cause deoptimization if FrameInstance.getFrame(FrameInstance.FrameAccess) is called with FrameInstance.FrameAccess.READ_WRITE or FrameInstance.FrameAccess.MATERIALIZE on the fast path. Instructions and flags for debugging such deoptimizations can be found in /truffle/docs/Optimizing.md#debugging-deoptimizations

      To get possible asynchronous stack frames, use TruffleStackTrace.getAsynchronousStackTrace(CallTarget, Frame) and provide call target and frame from the last FrameInstance.

      Parameters:
      visitor - the visitor that is called for every matching frame.
      Returns:
      the last result returned by the visitor (which is non-null to indicate that iteration should stop), or null if the whole stack was iterated.
      Since:
      0.8 or earlier

    • iterateFrames

      default <T> T iterateFrames(FrameInstanceVisitor<T> visitor, int skipFrames)
      Accesses the current stack, i.e., the contents of the Frames and the associated CallTargets. Iteration starts at the current frame and skips a number of frames provided as argument. Iteration continues as long as FrameInstanceVisitor.visitFrame(com.oracle.truffle.api.frame.FrameInstance), which is invoked for every FrameInstance, returns null. Any non-null result of the visitor indicates that frame iteration should stop.

      Instances of FrameInstance must note escape the invocation of FrameInstanceVisitor.visitFrame(FrameInstance). This rule is currently not enforced, but will be in future versions of Truffle.

      Note that this method can cause deoptimization if FrameInstance.getFrame(FrameInstance.FrameAccess) is called with FrameInstance.FrameAccess.READ_WRITE or FrameInstance.FrameAccess.MATERIALIZE on the fast path. Instructions and flags for debugging such deoptimizations can be found in /truffle/docs/Optimizing.md#debugging-deoptimizations

      To get possible asynchronous stack frames, use TruffleStackTrace.getAsynchronousStackTrace(CallTarget, Frame) and provide call target and frame from the last FrameInstance.

      Parameters:
      visitor - the visitor that is called for every matching frame.
      skipFrames - number of frames to skip before invoking the visitor
      Returns:
      the last result returned by the visitor (which is non-null to indicate that iteration should stop), or null if the whole stack was iterated.
      Since:
      21.1

    • getCapability

      <T> T getCapability(Class<T> capability)
      Requests a capability from the runtime.
      Parameters:
      capability - the type of the interface representing the capability
      Returns:
      an implementation of the capability or null if the runtime does not offer it
      Since:
      0.8 or earlier

    • notifyTransferToInterpreter

      void notifyTransferToInterpreter()
      Internal API method. Do not use.
      Since:
      0.8 or earlier

    • isProfilingEnabled

      boolean isProfilingEnabled()
      Whether or not the TruffleRuntime implementation can or wants to use gathered profiling information Truffle compilation. If this method returns false then all profiles in the com.oracle.truffle.api.utilities package are returning void implementations. If it returns true then all implementations gather profilinig information.
      Since:
      0.8 or earlier