Package com.oracle.truffle.api

## Interface TruffleRuntime

All Known Implementing Classes:
  `DefaultTruffleRuntime`

    public interface TruffleRuntime

Interface representing a Truffle runtime object. The runtime is responsible for creating call targets and performing optimizations for them.

### Method Summary

All Methods Instance Methods Abstract Methods
`Assumption` `createAssumption()` Creates a new assumption object that can be checked and invalidated.
`Assumption` `createAssumption​(java.lang.String name)` Creates a new assumption object with a given name that can be checked and invalidated.
`RootCallTarget` `createCallTarget​(RootNode rootNode)` Creates a new call target for a given root node.
`CompilerOptions` `createCompilerOptions()` Creates an object which allows you to test for support of and set options specific for this runtime.
`DirectCallNode` `createDirectCallNode​(CallTarget target)` Creates a new runtime specific version of `DirectCallNode`.
`IndirectCallNode` `createIndirectCallNode()` Creates a new runtime specific version of `IndirectCallNode`.
`LoopNode` `createLoopNode​(RepeatingNode body)` Experimental API.
`MaterializedFrame` `createMaterializedFrame​(java.lang.Object[] arguments)` Creates a new materialized frame object that can be used to store values.
`MaterializedFrame` `createMaterializedFrame​(java.lang.Object[] arguments, FrameDescriptor frameDescriptor)` Creates a new materialized frame object with the given frame descriptor that can be used to store values.
`VirtualFrame` `createVirtualFrame​(java.lang.Object[] arguments, FrameDescriptor frameDescriptor)` Creates a new virtual frame object that can be used to store values and is potentially optimizable by the runtime.
`FrameInstance` `getCallerFrame()` Accesses the caller frame.
`java.util.Collection<RootCallTarget>` `getCallTargets()` Returns a list of all still referenced `RootCallTarget` instances that were created using `createCallTarget(RootNode)`.
`<T> T` `getCapability​(java.lang.Class<T> capability)` Requests a capability from the runtime.
`FrameInstance` `getCurrentFrame()` Accesses the current frame, i.e., the frame of the closest `CallTarget`.
`java.lang.String` `getName()` Name describing this runtime implementation for debugging purposes.
`<T> T` `iterateFrames​(FrameInstanceVisitor<T> visitor)` Accesses the current stack, i.e., the contents of the `Frame`s and the associated `CallTarget`s.
`void` `notifyTransferToInterpreter()` Internal API method.

### Method Detail

#### getName

    java.lang.String getName()

Name describing this runtime implementation for debugging purposes.

Returns:
  the name as a String

#### createCallTarget

    RootCallTarget createCallTarget​(RootNode rootNode)

Creates a new call target for a given root node.

Parameters:
  `rootNode` - the root node whose `RootNode.execute(com.oracle.truffle.api.frame.VirtualFrame)` method represents the entry point
Returns:
  the new call target object

#### createDirectCallNode

    DirectCallNode createDirectCallNode​(CallTarget target)

Creates a new runtime specific version of `DirectCallNode`.

Parameters:
  `target` - the direct `CallTarget` to call
Returns:
  the new call node

#### createLoopNode

    LoopNode createLoopNode​(RepeatingNode body)

Experimental API. May change without notice.

#### createIndirectCallNode

    IndirectCallNode createIndirectCallNode()

Creates a new runtime specific version of `IndirectCallNode`.

Returns:
  the new call node

#### createAssumption

    Assumption createAssumption()

Creates a new assumption object that can be checked and invalidated.

Returns:
  the newly created assumption object

#### createAssumption

    Assumption createAssumption​(java.lang.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

#### createVirtualFrame

    VirtualFrame createVirtualFrame​(java.lang.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

#### createMaterializedFrame

    MaterializedFrame createMaterializedFrame​(java.lang.Object[] arguments)

Creates a new materialized frame object that can be used to store values.

Returns:
  the newly created materialized frame object

#### createMaterializedFrame

    MaterializedFrame createMaterializedFrame​(java.lang.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

#### createCompilerOptions

    CompilerOptions createCompilerOptions()

Creates an object which allows you to test for support of and set options specific for this runtime.

Returns:
  the newly created compiler options object

#### iterateFrames

    <T> T iterateFrames​(FrameInstanceVisitor<T> visitor)

Accesses the current stack, i.e., the contents of the `Frame`s and the associated `CallTarget`s. Iteration starts at the caller frame, i.e., it does not include 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.

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.

#### getCallerFrame

    FrameInstance getCallerFrame()

Accesses the caller frame. This is a convenience method that returns the first frame that is passed to the visitor of `iterateFrames(com.oracle.truffle.api.frame.FrameInstanceVisitor<T>)`.

#### getCurrentFrame

    FrameInstance getCurrentFrame()

Accesses the current frame, i.e., the frame of the closest `CallTarget`. It is important to note that this `FrameInstance` supports only slow path access.

#### getCapability

    <T> T getCapability​(java.lang.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

#### getCallTargets

    java.util.Collection<RootCallTarget> getCallTargets()

Returns a list of all still referenced `RootCallTarget` instances that were created using `createCallTarget(RootNode)`.

#### notifyTransferToInterpreter

    void notifyTransferToInterpreter()

Internal API method. Do not use.