com.oracle.truffle.api.nodes

Class RootNode

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.nodes.RootNode

All Implemented Interfaces:

NodeInterface, Cloneable

public abstract class RootNode
extends Node

Represents the root node in a Truffle AST. The root node is a node that allows to be executed using a frame instance created by the framework. Please note that the RootNode should not be executed directly but using CallTarget.call(Object...). The structure of the frame is provided by the frame descriptor passed in the constructor. A root node has always a null parent and cannot be replaced.

Construction

The root node can be constructed with a language implementation if it is available. The language implementation instance is obtainable while TruffleLanguage.createContext(Env) or TruffleLanguage.parse(ParsingRequest) is executed. If no language environment is available, then null can be passed. Please note that root nodes with null language are considered not instrumentable and have no access to the language or its public information.

Execution

In order to execute a root node, a call target needs to be created using TruffleRuntime.createCallTarget(RootNode). This allows the runtime system to optimize the execution of the AST. The CallTarget can either be called directly from runtime code or direct and indirect call nodes can be created, inserted in a child field and called. The use of direct call nodes allows the framework to automatically inline and further optimize call sites based on heuristics.

After several calls to a call target or call node, the root node might get compiled using partial evaluation. The details of the compilation heuristic are unspecified, therefore the Truffle runtime system might decide to not compile at all.

Cardinalities

One root node instance refers to other classes using the following cardinalities:

• one language
• one call target
• many created language contexts

Instrumentation

A root node can be instrumented if the following conditions apply:

• A non-null language is passed in the root node constructor.
• RootNode.isInstrumentable() is overridden and returns true.
• RootNode.getSourceSection() is overridden and returns a non-null value.
• The AST contains at least one node that is annotated with Instrumentable .

Note: It is recommended to override RootNode.getSourceSection() and provide a source section if available. This allows for better testing/tracing/tooling. If no concrete source section is available please consider using Source.createUnavailableSection().

Since:

0.8 or earlier

Nested Class Summary

Nested classes/interfaces inherited from class com.oracle.truffle.api.nodes.Node

Node.Child, Node.Children

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RootNode(TruffleLanguage<?> language) Creates new root node with a given language instance.
protected	RootNode(TruffleLanguage<?> language, FrameDescriptor frameDescriptor) Creates new root node given an language environment and frame descriptor.

Method Summary

Modifier and Type	Method and Description
protected RootNode	cloneUninitialized() Creates an uninitialized copy of an already initialized/executed root node if it is supported.
Node	copy() Creates a shallow copy of this node.
static RootNode	createConstantNode(Object constant) Helper method to create a root node that always returns the same value.
abstract Object	execute(VirtualFrame frame) Executes this function using the specified frame and returns the result value.
RootCallTarget	getCallTarget()
CompilerOptions	getCompilerOptions() Get compiler options specific to this RootNode.
FrameDescriptor	getFrameDescriptor()
<C extends TruffleLanguage> C	getLanguage(Class<C> languageClass) Returns the language instance associated with this root node.
LanguageInfo	getLanguageInfo() Returns public information about the language.
String	getName() A description of the AST (expected to be a method or procedure name in most languages) that identifies the AST for the benefit of guest language programmers using tools; it might appear, for example in the context of a stack dump or trace and is not expected to be called often.
SourceSection	getSourceSection() Returns the source section associated with this RootNode.
protected boolean	isCloneUninitializedSupported() Returns true if RootNode.cloneUninitialized() can be used to create uninitialized copies of an already initialized / executed root node.
boolean	isCloningAllowed() Returns true if this RootNode is allowed to be cloned.
protected boolean	isInstrumentable() Does this contain AST content that it is possible to instrument.

Methods inherited from class com.oracle.truffle.api.nodes.Node

accept, adoptChildren, atomic, atomic, deepCopy, getChildren, getCost, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, insert, insert, isSafelyReplaceableBy, isTaggedWith, onReplace, replace, replace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RootNode

protected RootNode(TruffleLanguage<?> language)

Creates new root node with a given language instance. The language instance is obtainable while TruffleLanguage.createContext(Env) or TruffleLanguage.parse(ParsingRequest) is executed. If no language environment is available, then null can be passed. Please note that root nodes with null language are considered not instrumentable and have no access to the language or its public information.

Parameters:

language - the language this root node is associated with

Since:

0.25

RootNode

protected RootNode(TruffleLanguage<?> language,
                   FrameDescriptor frameDescriptor)

Creates new root node given an language environment and frame descriptor. The language instance is obtainable while TruffleLanguage.createContext(Env) or TruffleLanguage.parse(ParsingRequest) is executed. If no language environment is available, then null can be passed. Please note that root nodes with null language are considered not instrumentable and have no access to the language or its public information.

Parameters:

language - the language this root node is associated with

Since:

0.25

Method Detail

getLanguage

public final <C extends TruffleLanguage> C getLanguage(Class<C> languageClass)

Returns the language instance associated with this root node. The language instance is intended for internal use in languages and is only accessible if the concrete type of the language is known. Public information about the language can be accessed using RootNode.getLanguageInfo(). The language is null if the root node is not associated with a null language.

Since:

0.25

See Also:

RootNode.getLanguageInfo()

getLanguageInfo

public final LanguageInfo getLanguageInfo()

Returns public information about the language. The language can be assumed equal if the instances of the language info instance are the same. To access internal details of the language within the language implementation use RootNode.getLanguage(Class).

Since:

0.25

copy

public Node copy()

Description copied from class: Node

Creates a shallow copy of this node.

Overrides:

copy in class Node

Returns:

the new copy

Since:

0.8 or earlier

getSourceSection

public SourceSection getSourceSection()

Returns the source section associated with this RootNode. Returns null if by default.

Overrides:

getSourceSection in class Node

Returns:

the source code represented by this Node

Since:

0.13

getName

public String getName()

A description of the AST (expected to be a method or procedure name in most languages) that identifies the AST for the benefit of guest language programmers using tools; it might appear, for example in the context of a stack dump or trace and is not expected to be called often.

In some languages AST "compilation units" may have no intrinsic names. When no information is available, language implementations might simply use the first few characters of the code, followed by "...". Language implementations should assign a more helpful name whenever it becomes possible, for example when a functional value is assigned. This means that the name might not be stable over time.

Language execution semantics should not depend on either this name or the way that it is formatted. The name should be presented in the way expected to be most useful for programmers.

Returns:

a name that helps guest language programmers identify code corresponding to the AST, possibly null if the language implementation is unable to provide any useful information.

Since:

0.15

isCloningAllowed

public boolean isCloningAllowed()

Returns true if this RootNode is allowed to be cloned. The runtime system might decide to create deep copies of the RootNode in order to gather context sensitive profiling feedback. The default implementation returns false. Guest language specific implementations may want to return true here to indicate that gathering call site specific profiling information might make sense for this RootNode .

Returns:

true if cloning is allowed else false.

Since:

0.8 or earlier

isCloneUninitializedSupported

protected boolean isCloneUninitializedSupported()

Returns true if RootNode.cloneUninitialized() can be used to create uninitialized copies of an already initialized / executed root node. By default, or if this method returns false, an optimizing Truffle runtime might need to copy the AST before it is executed for the first time to ensure it is able to create new uninitialized copies when needed. By returning true and therefore supporting uninitialized copies an optimizing runtime does not need to keep a reference to an uninitialized copy on its own and might therefore be able to save memory. The returned boolean needs to be immutable for a RootNode instance.

Returns:

true if calls to uninitialized copies are supported.

Since:

0.24

See Also:

RootNode.cloneUninitialized()

cloneUninitialized

protected RootNode cloneUninitialized()

Creates an uninitialized copy of an already initialized/executed root node if it is supported. Throws an UnsupportedOperationException exception by default. By default, or if RootNode.isCloneUninitializedSupported() returns false, an optimizing Truffle runtime might need to copy the root node before it is executed for the first time to ensure it is able to create new uninitialized copies when needed. By supporting uninitialized copies an optimizing runtime does not need to keep a reference to an uninitialized copy on its own and might therefore be able to save memory.

Two common strategies to implement RootNode.cloneUninitialized() are:

• Reparsing: Support it by keeping a reference to the original source code including the lexical scope and create the uninitialized copy of the root node by reparsing the source.
• Resetting: Support it by traversing the Node tree and derive an uninitialized copy from each initialized node.

Returns:

an uninitialized copy of this root node if supported.

Throws:

UnsupportedOperationException - if not supported

Since:

0.24

See Also:

RootNode.isCloneUninitializedSupported()

execute

public abstract Object execute(VirtualFrame frame)

Executes this function using the specified frame and returns the result value.

Parameters:

frame - the frame of the currently executing guest language method

Returns:

the value of the execution

Since:

0.8 or earlier

getCallTarget

public final RootCallTarget getCallTarget()

Since:

0.8 or earlier

getFrameDescriptor

public final FrameDescriptor getFrameDescriptor()

Since:

0.8 or earlier

getCompilerOptions

public CompilerOptions getCompilerOptions()

Get compiler options specific to this RootNode.

Since:

0.8 or earlier

isInstrumentable

protected boolean isInstrumentable()

Does this contain AST content that it is possible to instrument.

Since:

0.8 or earlier

createConstantNode

public static RootNode createConstantNode(Object constant)

Helper method to create a root node that always returns the same value. Certain operations (especially inter-operability API) require return of stable root nodes. To simplify creation of such nodes, here is a factory method that can create RootNode that returns always the same value.

Parameters:

constant - the constant to return

Returns:

root node returning the constant

Since:

0.8 or earlier