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 Summary

Modifier and Type	Method and Description
Assumption	createAssumption() Creates a new assumption object that can be checked and invalidated.
Assumption	createAssumption(String name) Creates a new assumption object with a given name that can be checked and invalidated.
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) Creates a new loop node with an implementation provided by a Truffle runtime implementation.
MaterializedFrame	createMaterializedFrame(Object[] arguments) Creates a new materialized frame object that can be used to store values.
MaterializedFrame	createMaterializedFrame(Object[] arguments, FrameDescriptor frameDescriptor) Creates a new materialized frame object with the given frame descriptor that can be used to store values.
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.
FrameInstance	getCallerFrame() Accesses the caller frame.
<T> T	getCapability(Class<T> capability) Requests a capability from the runtime.
FrameInstance	getCurrentFrame() Accesses the current frame, i.e., the frame of the closest CallTarget.
String	getName() Name describing this runtime implementation for debugging purposes.
boolean	isProfilingEnabled() Whether or not the TruffleRuntime implementation can or wants to use gathered profiling information Truffle compilation.
<T> T	iterateFrames(FrameInstanceVisitor<T> visitor) Accesses the current stack, i.e., the contents of the Frames and the associated CallTargets.
void	notifyTransferToInterpreter() Internal API method.

Method Detail

getName

String getName()

Name describing this runtime implementation for debugging purposes.

Returns:

the name as a String

Since:

0.8 or earlier

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

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:

usage example

createIndirectCallNode

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

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

Since:

0.8 or earlier

iterateFrames

<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.

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

getCallerFrame

FrameInstance getCallerFrame()

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

Since:

0.8 or earlier

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.

Since:

0.8 or earlier

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