Node (GraalVM Truffle Java API Reference)

java.lang.Object
- com.oracle.truffle.api.nodes.Node

All Implemented Interfaces:

NodeInterface, Cloneable

Direct Known Subclasses:

BlockNode, DirectCallNode, ExecutableNode, ExecutionEventNode, IndirectCallNode, Library, LoopNode, MutableTruffleString.AsManagedNode, MutableTruffleString.AsMutableTruffleStringNode, MutableTruffleString.ConcatNode, MutableTruffleString.ForceEncodingNode, MutableTruffleString.FromByteArrayNode, MutableTruffleString.FromNativePointerNode, MutableTruffleString.SubstringByteIndexNode, MutableTruffleString.SubstringNode, MutableTruffleString.SwitchEncodingNode, MutableTruffleString.WriteByteNode, ProbeNode, TruffleString.AsManagedNode, TruffleString.AsNativeNode, TruffleString.AsTruffleStringNode, TruffleString.ByteIndexOfAnyByteNode, TruffleString.ByteIndexOfCodePointNode, TruffleString.ByteIndexOfCodePointSetNode, TruffleString.ByteIndexOfStringNode, TruffleString.ByteIndexToCodePointIndexNode, TruffleString.ByteLengthOfCodePointNode, TruffleString.CharIndexOfAnyCharUTF16Node, TruffleString.CodePointAtByteIndexNode, TruffleString.CodePointAtIndexNode, TruffleString.CodePointIndexToByteIndexNode, TruffleString.CodePointLengthNode, TruffleString.CodeRangeEqualsNode, TruffleString.CompareBytesNode, TruffleString.CompareCharsUTF16Node, TruffleString.CompareIntsUTF32Node, TruffleString.ConcatNode, TruffleString.CopyToByteArrayNode, TruffleString.CopyToNativeMemoryNode, TruffleString.CreateBackwardCodePointIteratorNode, TruffleString.CreateCodePointIteratorNode, TruffleString.EqualNode, TruffleString.ForceEncodingNode, TruffleString.FromByteArrayNode, TruffleString.FromCharArrayUTF16Node, TruffleString.FromCodePointNode, TruffleString.FromIntArrayUTF32Node, TruffleString.FromJavaStringNode, TruffleString.FromLongNode, TruffleString.FromNativePointerNode, TruffleString.GetByteCodeRangeNode, TruffleString.GetCodeRangeImpreciseNode, TruffleString.GetCodeRangeNode, TruffleString.GetInternalByteArrayNode, TruffleString.GetInternalNativePointerNode, TruffleString.GetStringCompactionLevelNode, TruffleString.HashCodeNode, TruffleString.IndexOfCodePointNode, TruffleString.IndexOfStringNode, TruffleString.IntIndexOfAnyIntUTF32Node, TruffleString.IsValidNode, TruffleString.LastByteIndexOfCodePointNode, TruffleString.LastByteIndexOfStringNode, TruffleString.LastIndexOfCodePointNode, TruffleString.LastIndexOfStringNode, TruffleString.MaterializeNode, TruffleString.ParseDoubleNode, TruffleString.ParseIntNode, TruffleString.ParseLongNode, TruffleString.ReadByteNode, TruffleString.ReadCharUTF16Node, TruffleString.RegionEqualByteIndexNode, TruffleString.RegionEqualNode, TruffleString.RepeatNode, TruffleString.SubstringByteIndexNode, TruffleString.SubstringNode, TruffleString.SwitchEncodingNode, TruffleString.ToJavaStringNode, TruffleString.ToValidStringNode, TruffleString.WithMask.CreateNode, TruffleString.WithMask.CreateUTF16Node, TruffleString.WithMask.CreateUTF32Node, TruffleStringBuilder.AppendByteNode, TruffleStringBuilder.AppendCharUTF16Node, TruffleStringBuilder.AppendCodePointNode, TruffleStringBuilder.AppendIntNumberNode, TruffleStringBuilder.AppendJavaStringUTF16Node, TruffleStringBuilder.AppendLongNumberNode, TruffleStringBuilder.AppendStringNode, TruffleStringBuilder.AppendSubstringByteIndexNode, TruffleStringBuilder.ToStringNode, TruffleStringIterator.NextNode, TruffleStringIterator.PreviousNode
```
public abstract class Node
extends Object
implements NodeInterface, Cloneable
```
Abstract base class for all Truffle nodes.

Since:

0.8 or earlier

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Node.Child` Marks fields that represent child nodes of this node.
`static interface`	`Node.Children` Marks array fields that are children of this node.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Node()

Constructors
Modifier	Constructor and Description
`protected`	`Node()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`accept(NodeVisitor nodeVisitor)` Invokes the `NodeVisitor.visit(Node)` method for this node and recursively also for all child nodes.
`void`	`adoptChildren()`
`<T> T`	`atomic(Callable<T> closure)`
`void`	`atomic(Runnable closure)`
`Node`	`copy()` Creates a shallow copy of this node.
`Node`	`deepCopy()` Creates a deep copy of this node.
`Iterable<Node>`	`getChildren()` Iterator over the children of this node.
`NodeCost`	`getCost()` Returns a rough estimate for the cost of this `Node`.
`Map<String,Object>`	`getDebugProperties()` Returns properties of this node interesting for debugging and can be overwritten by subclasses to add their own custom properties.
`String`	`getDescription()` Returns a user-readable description of the purpose of the Node, or "" if no description is available.
`SourceSection`	`getEncapsulatingSourceSection()` Retrieves the segment of guest language source code that is represented by this Node, if present; otherwise retrieves the segment represented by the nearest AST ancestor that has this information.
`protected Lock`	`getLock()` Returns a lock object that can be used to synchronize modifications to the AST.
`Node`	`getParent()` The current parent node of this node.
`RootNode`	`getRootNode()` Get the root node of the tree a node belongs to.
`SourceSection`	`getSourceSection()` Retrieves the segment of guest language source code that is represented by this Node.
`<T extends Node> T`	`insert(T newChild)` Inserts an new node into an AST that was already `adopted` by a `parent`.
`<T extends Node> T[]`	`insert(T[] newChildren)` Inserts new node children into an AST that was already `adopted` by a `parent`.
`boolean`	`isAdoptable()` Returns `true` if this node can be adopted by a parent.
`boolean`	`isSafelyReplaceableBy(Node newNode)` Checks if this node can be replaced by another node: tree structure & type.
`protected void`	`notifyInserted(Node node)` Notifies the framework about the insertion of one or more nodes during execution.
`protected void`	`onReplace(Node newNode, CharSequence reason)` Intended to be implemented by subclasses of `Node` to receive a notification when the node is rewritten.
`<T extends Node> T`	`replace(T newNode)` Replaces this node with another node.
`<T extends Node> T`	`replace(T newNode, CharSequence reason)` Replaces this node with another node.
`void`	`reportPolymorphicSpecialize()` Notifies the runtime that this node specialized to a polymorphic state.
`String`	`toString()` Converts this node to a textual representation useful for debugging.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Node
```
protected Node()
```
    Since:
    
    0.8 or earlier
- Method Detail
  - getCost
```
public NodeCost getCost()
```
    Returns a rough estimate for the cost of this Node. This estimate can be used by runtime systems or guest languages to implement heuristics based on Truffle ASTs. This method is intended to be overridden by subclasses. The default implementation returns the value of NodeInfo.cost() of the NodeInfo annotation declared at the subclass. If no NodeInfo annotation is declared the method returns NodeCost.MONOMORPHIC as a default value.
    
    Since:
    
    0.8 or earlier
  - getSourceSection
```
public SourceSection getSourceSection()
```
    Retrieves the segment of guest language source code that is represented by this Node. The default implementation of this method returns null. If your node represents a segment of the source code, override this method and return a eagerly or lazily computed source section value. This method is not designed to be invoked on compiled code paths. May be called on any thread and without a language context being active.
    Simple example implementation using a simple implementation using a field:
```
abstract class SimpleNode extends Node {

    private SourceSection sourceSection;

    void setSourceSection(SourceSection sourceSection) {
        this.sourceSection = sourceSection;
    }

    @Override
    public SourceSection getSourceSection() {
        return sourceSection;
    }
}
```
    Recommended implementation computing the source section lazily from primitive fields:
```
abstract class RecommendedNode extends Node {

    private static final int NO_SOURCE = -1;

    private int sourceCharIndex = NO_SOURCE;
    private int sourceLength;

    public abstract Object execute(VirtualFrame frame);

    // invoked by the parser to set the source
    void setSourceSection(int charIndex, int length) {
        assert sourceCharIndex == NO_SOURCE : "source should only be set once";
        this.sourceCharIndex = charIndex;
        this.sourceLength = length;
    }

    @Override
    public final SourceSection getSourceSection() {
        if (sourceCharIndex == NO_SOURCE) {
            // AST node without source
            return null;
        }
        RootNode rootNode = getRootNode();
        if (rootNode == null) {
            // not yet adopted yet
            return null;
        }
        Source source = rootNode.getSourceSection().getSource();
        return source.createSection(sourceCharIndex, sourceLength);
    }

}
```
    Returns:
    
    the source code represented by this Node
    
    Since:
    
    0.8 or earlier
  - getEncapsulatingSourceSection
```
public SourceSection getEncapsulatingSourceSection()
```
    Retrieves the segment of guest language source code that is represented by this Node, if present; otherwise retrieves the segment represented by the nearest AST ancestor that has this information. Can be called on any thread and without a language context.
    
    Returns:
    
    an approximation of the source code represented by this Node
    
    Since:
    
    0.8 or earlier
  - isAdoptable
```
public boolean isAdoptable()
```
    Returns true if this node can be adopted by a parent. This method is intended to be overriden by subclasses. If nodes need to be statically shared that they must not be adoptable, because otherwise the parent reference might cause a memory leak. If a node is not adoptable then then it is guaranteed that the parent pointer remains null at all times, even if the node is tried to be adopted by a parent.
    Implementations of Node.isAdoptable() are required to fold to a constant result when compiled with a constant receiver.
    
    Since:
    
    19.0
  - insert
```
public final <T extends Node> T[] insert(T[] newChildren)
```
    Inserts new node children into an AST that was already adopted by a parent. The new children need to be assigned to its children field after insert was called.
    
    Parameters:
    
    newChildren - the array of new children whose parent should be updated
    
    Returns:
    
    the array of new children
    
    Since:
    
    0.8 or earlier
  - insert
```
public final <T extends Node> T insert(T newChild)
```
    Inserts an new node into an AST that was already adopted by a parent. The new child needs to be assigned to its child field after insert was called.
    
    Parameters:
    
    newChild - the new child whose parent should be updated
    
    Returns:
    
    the new child
    
    Since:
    
    0.8 or earlier
  - notifyInserted
```
protected final void notifyInserted(Node node)
```
    Notifies the framework about the insertion of one or more nodes during execution. Otherwise, the framework assumes that instrumentable nodes remain unchanged after their root node is first executed. Insertions don't need to be notified if it is known that none of the inserted nodes are instrumentable.
    The provided Node and its children must be adopted in the AST before invoking this method. The caller must ensure that this method is invoked only once for a given node and its children.
    Example usage:
```
class MyRootNode extends RootNode {

    protected MyRootNode(MyLanguage language) {
        super(language);
    }

    @Child InstrumentableLanguageNode child;

    @Override
    public Object execute(VirtualFrame frame) {
        if (child == null) {
            CompilerDirectives.transferToInterpreterAndInvalidate();
            child = insert(new InstrumentableLanguageNode());
            notifyInserted(child);
        }
        return child.execute(frame);
    }

}
```
    Parameters:
    
    node - the node tree that got inserted.
    
    Since:
    
    0.27
  - adoptChildren
```
public final void adoptChildren()
```
    Since:
    
    0.8 or earlier
  - getDebugProperties
```
public Map<String,Object> getDebugProperties()
```
    Returns properties of this node interesting for debugging and can be overwritten by subclasses to add their own custom properties.
    
    Returns:
    
    the properties as a key/value hash map
    
    Since:
    
    0.8 or earlier
  - getParent
```
public final Node getParent()
```
    The current parent node of this node.
    
    Returns:
    
    the parent node
    
    Since:
    
    0.8 or earlier
  - replace
```
public final <T extends Node> T replace(T newNode,
                                        CharSequence reason)
```
    Replaces this node with another node. If there is a source section (see Node.getSourceSection()) associated with this node, it is transferred to the new node.
    
    Parameters:
    
    newNode - the new node that is the replacement
    
    reason - a description of the reason for the replacement
    
    Returns:
    
    the new node
    
    Since:
    
    0.8 or earlier
  - replace
```
public final <T extends Node> T replace(T newNode)
```
    Replaces this node with another node. If there is a source section (see Node.getSourceSection()) associated with this node, it is transferred to the new node.
    
    Parameters:
    
    newNode - the new node that is the replacement
    
    Returns:
    
    the new node
    
    Since:
    
    0.8 or earlier
  - isSafelyReplaceableBy
```
public final boolean isSafelyReplaceableBy(Node newNode)
```
    Checks if this node can be replaced by another node: tree structure & type.
    
    Since:
    
    0.8 or earlier
  - onReplace
```
protected void onReplace(Node newNode,
                         CharSequence reason)
```
    Intended to be implemented by subclasses of Node to receive a notification when the node is rewritten. This method is invoked before the actual replace has happened.
    
    Parameters:
    
    newNode - the replacement node
    
    reason - the reason the replace supplied
    
    Since:
    
    0.8 or earlier
  - accept
```
public final void accept(NodeVisitor nodeVisitor)
```
    Invokes the NodeVisitor.visit(Node) method for this node and recursively also for all child nodes.
    
    Parameters:
    
    nodeVisitor - the visitor
    
    Since:
    
    0.8 or earlier
  - getChildren
```
public final Iterable<Node> getChildren()
```
    Iterator over the children of this node.
    
    Returns:
    
    the iterator
    
    Since:
    
    0.8 or earlier
  - copy
```
public Node copy()
```
    Creates a shallow copy of this node.
    
    Returns:
    
    the new copy
    
    Since:
    
    0.8 or earlier
  - deepCopy
```
public Node deepCopy()
```
    Creates a deep copy of this node.
    
    Returns:
    
    the new deep copy
    
    Since:
    
    0.8 or earlier
  - getRootNode
```
public final RootNode getRootNode()
```
    Get the root node of the tree a node belongs to.
    
    Returns:
    
    the RootNode or null if there is none.
    
    Since:
    
    0.8 or earlier
  - reportPolymorphicSpecialize
```
public final void reportPolymorphicSpecialize()
```
    Notifies the runtime that this node specialized to a polymorphic state. This includes specializations that increase "level" of polymorphism (e.g. Adding another element to an existing inline cache). The runtime can use this information to, if allowed, create a deep copy of the RootNode hosting this node and gather context sensitive profiling feedback.
    
    Since:
    
    0.33
  - toString
```
public String toString()
```
    Converts this node to a textual representation useful for debugging.
    
    Overrides:
    
    toString in class Object
    
    Since:
    
    0.8 or earlier
  - atomic
```
public final void atomic(Runnable closure)
```
    Since:
    
    0.8 or earlier
  - atomic
```
public final <T> T atomic(Callable<T> closure)
```
    Since:
    
    0.8 or earlier
  - getLock
```
protected final Lock getLock()
```
    Returns a lock object that can be used to synchronize modifications to the AST. Don't lock if you call into foreign code with potential recursions to avoid deadlocks. Use responsibly.
    
    Since:
    
    0.19
  - getDescription
```
public String getDescription()
```
    Returns a user-readable description of the purpose of the Node, or "" if no description is available. Can be called on any thread and without a language context.
    
    Since:
    
    0.8 or earlier

Class Node

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Node

Method Detail

getCost

getSourceSection

getEncapsulatingSourceSection

isAdoptable

insert

insert

notifyInserted

adoptChildren

getDebugProperties

getParent

replace

replace

isSafelyReplaceableBy

onReplace

accept

getChildren

copy

deepCopy

getRootNode

reportPolymorphicSpecialize

toString

atomic

atomic

getLock

getDescription