public abstract class RootNode extends ExecutableNode
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.
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 don't
have access to its public language information.
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.
language
call target
created language contexts
language is passed in the root node constructor.
RootNode.isInstrumentable() is overridden and returns true.
Node.getSourceSection() is overridden and returns a non-null value.
Instrumentable.
StandardTags.
Note: It is recommended to override Node.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().
Node.Child, Node.Children| 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.
|
| 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() |
String |
getName()
Returns a simple name 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.
|
String |
getQualifiedName()
Returns a qualified name of the AST that in the best case uniquely identifiers the method.
|
boolean |
isCaptureFramesForTrace()
Returns
true if a TruffleException leaving this node should capture
Frame objects in its stack trace in addition to the default information. |
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.
|
boolean |
isInternal()
Returns
true if this root node should be considered internal and not be shown to
a guest language programmer. |
protected void |
setCallTarget(RootCallTarget callTarget) |
getLanguageInfoaccept, adoptChildren, atomic, atomic, deepCopy, getChildren, getCost, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, lookupContextReference, lookupLanguageReference, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toStringprotected RootNode(TruffleLanguage<?> language)
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 don't have access to its
public language information.language - the language this root node is associated withprotected RootNode(TruffleLanguage<?> language, FrameDescriptor frameDescriptor)
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 don't have access to its
public language information.language - the language this root node is associated withpublic String getQualifiedName()
name is used by
default. A root node that represents a Java method could consist of the package name, the
class name and the method name. E.g. mypackage.MyClass.myMethodpublic String getName()
myMethod
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.
null if the language implementation is unable to provide any useful
information.public boolean isInternal()
true if this root node should be considered internal and not be shown to
a guest language programmer. This method has effect on tools and guest language stack traces.
By default a RootNode is internal if no language was passed in the constructor or if
the root source section is set and points to an internal source.
This method is intended to be overwritten by guest languages, when the node's source is
internal, the implementation should respect that. Can be called on any thread and without a
language context.
This method may be invoked on compiled code paths. It is recommended to implement this method such that it returns a compilation final constant.
public boolean isCaptureFramesForTrace()
true if a TruffleException leaving this node should capture
Frame objects in its stack trace in addition to the default information. This is
false by default to avoid the attached overhead. The captured frames are then
accessible through TruffleStackTraceElement.getFrame()public boolean isCloningAllowed()
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
.true if cloning is allowed else false.protected boolean isCloneUninitializedSupported()
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.true if calls to uninitialized copies are
supported.RootNode.cloneUninitialized()protected RootNode cloneUninitialized()
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:
Node tree and derive an
uninitialized copy from each initialized node.
UnsupportedOperationException - if not supportedRootNode.isCloneUninitializedSupported()public abstract Object execute(VirtualFrame frame)
execute in class ExecutableNodeframe - the frame of the currently executing guest language methodpublic final RootCallTarget getCallTarget()
public final FrameDescriptor getFrameDescriptor()
protected final void setCallTarget(RootCallTarget callTarget)
public CompilerOptions getCompilerOptions()
RootNode.protected boolean isInstrumentable()
public static RootNode createConstantNode(Object constant)
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.constant - the constant to return