Node

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

All Implemented Interfaces:

NodeInterface, Cloneable

Direct Known Subclasses:

DirectCallNode, ExecutionEventNode, IndirectCallNode, LoopNode, ProbeNode, RootNode
```
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.
`protected <T extends Node> T`	`insert(T newChild)` Method that updates the link to the parent in the specified new child node to this node.
`protected <T extends Node> T[]`	`insert(T[] newChildren)` Method that updates the link to the parent in the array of specified new child nodes to this node.
`boolean`	`isSafelyReplaceableBy(Node newNode)` Checks if this node can be replaced by another node: tree structure & type.
`protected boolean`	`isTaggedWith(Class<?> tag)` Returns `true` if this node should be considered tagged by a given tag else `false`.
`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.
`String`	`toString()` Converts this node to a textual representation useful for debugging.

Methods inherited from class java.lang.Object
clone, equals, finalize, 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 final or CompilerDirectives.CompilationFinal field in your node to the caller. To define node with fixed SourceSection that doesn't change after node construction use:
```
private final SourceSection section;

NodeWithFixedSourceSection(SourceSection section) {
    this.section = section;
}

@Override
public SourceSection getSourceSection() {
    return section;
}
```
    To create a node which can associate and change the SourceSection later at any point of time use:
```
@CompilerDirectives.CompilerDirectives.CompilationFinal private SourceSection section;

final void changeSourceSection(SourceSection sourceSection) {
    CompilerDirectives.transferToInterpreterAndInvalidate();
    this.section = sourceSection;
}

@Override
public SourceSection getSourceSection() {
    return section;
}
```
    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.
    
    Returns:
    
    an approximation of the source code represented by this Node
    
    Since:
    
    0.8 or earlier
  - insert
```
protected final <T extends Node> T[] insert(T[] newChildren)
```
    Method that updates the link to the parent in the array of specified new child nodes to this node.
    
    Parameters:
    
    newChildren - the array of new children whose parent should be updated
    
    Returns:
    
    the array of new children
    
    Since:
    
    0.8 or earlier
  - insert
```
protected final <T extends Node> T insert(T newChild)
```
    Method that updates the link to the parent in the specified new child node to this node.
    
    Parameters:
    
    newChild - the new child whose parent should be updated
    
    Returns:
    
    the new child
    
    Since:
    
    0.8 or earlier
  - 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
  - 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
  - isTaggedWith
```
protected boolean isTaggedWith(Class<?> tag)
```
    Returns true if this node should be considered tagged by a given tag else false. The method is only invoked for tags which are explicitly declared as provided by the language. If the source section of the node returns null then this node is considered to be not tagged by any tag.
    Tags are used by guest languages to indicate that a node is a member of a certain category of nodes. For example a debugger instrument might require a guest language to tag all nodes as halt locations that should be considered as such.
    The node implementor may decide how to implement tagging for nodes. The simplest way to implement tagging using Java types is by overriding the Node.isTaggedWith(Class) method. This example shows how to tag a node subclass and all its subclasses as expression and statement:
```
class ExpressionNode extends Node {

    @Override
    protected boolean isTaggedWith(Class<?> tag) {
        if (tag == ExpressionTag.class) {
            return true;
        }
        return super.isTaggedWith(tag);
    }
}
```
    Often it is impossible to just rely on the node's Java type to implement tagging. This example shows how to use local state to implement tagging for a node.
```
class StatementNode extends Node {
    private boolean isDebuggerHalt;

    public void setDebuggerHalt(boolean isDebuggerHalt) {
        this.isDebuggerHalt = isDebuggerHalt;
    }

    @Override
    protected boolean isTaggedWith(Class<?> tag) {
        if (tag == Debugger.HaltTag.class) {
            return isDebuggerHalt;
        }
        return super.isTaggedWith(tag);
    }
}
```
    The implementation of isTaggedWith method must ensure that its result is stable after the parent root node was wrapped in a CallTarget using TruffleRuntime.createCallTarget(RootNode). The result is stable if the result of calling this method for a particular tag remains always the same.
    Parameters:
    
    tag - the class provided by the language
    
    Returns:
    
    true if the node should be considered tagged by a tag else false.
    
    Since:
    
    0.12
  - getDescription
```
public String getDescription()
```
    Returns a user-readable description of the purpose of the Node, or "" if no description is available.
    
    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

insert

insert

adoptChildren

getDebugProperties

getParent

replace

replace

isSafelyReplaceableBy

onReplace

accept

getChildren

copy

deepCopy

getRootNode

toString

atomic

atomic

getLock

isTaggedWith

getDescription