Class Node

java.lang.Object
com.oracle.truffle.api.nodes.Node
All Implemented Interfaces:
NodeInterface, Cloneable
Direct Known Subclasses:
DirectCallNode, IndirectCallNode, LoopNode, ProbeNode, RootNode

public abstract class Node extends Object implements NodeInterface, Cloneable
Abstract base class for all Truffle nodes.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Marks fields that represent child nodes of this node.
    static @interface 
    Marks array fields that are children of this node.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
     
    protected
    Node(SourceSection sourceSection)
     
  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    accept(NodeVisitor nodeVisitor)
    Invokes the NodeVisitor.visit(Node) method for this node and recursively also for all child nodes.
    final void
     
    final void
    Assigns a link to a guest language source section to this node.
    final void
    atomic(Runnable closure)
     
    final <T> T
    atomic(Callable<T> closure)
     
    final void
    Clears any previously assigned guest language source code from this node.
    protected final Object
    Deprecated.
    Creates a shallow copy of this node.
    final Iterable<Node>
    Iterator over the children of this node.
    Returns a rough estimate for the cost of this Node.
    Returns properties of this node interesting for debugging and can be overwritten by subclasses to add their own custom properties.
    Returns a user-readable description of the purpose of the Node, or "" if no description is available.
    Retrieves the guest language source code section that is currently assigned to this node.
    Returns a string representing the language this node has been implemented for.
    final Node
    The current parent node of this node.
    final RootNode
    Get the root node of the tree a node belongs to.
    Retrieves the guest language source code section that is currently assigned to this node.
    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.
    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.
    final boolean
    Checks if this node is properly adopted by a parent and can be replaced.
    protected void
    Subclasses of Node can implement this method to execute extra functionality when a node is effectively inserted into the AST.
    protected void
    onReplace(Node newNode, CharSequence reason)
    Intended to be implemented by subclasses of Node to receive a notification when the node is rewritten.
    final <T extends Node>
    T
    replace(T newNode)
    Replaces this node with another node.
    final <T extends Node>
    T
    replace(T newNode, CharSequence reason)
    Replaces this node with another node.
    Converts this node to a textual representation useful for debugging.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • Node

      protected Node()
    • Node

      protected Node(SourceSection sourceSection)
  • Method Details

    • assignSourceSection

      public final void assignSourceSection(SourceSection section)
      Assigns a link to a guest language source section to this node.
      Parameters:
      section - the object representing a section in guest language source code
    • 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.
    • clearSourceSection

      public final void clearSourceSection()
      Clears any previously assigned guest language source code from this node.
    • getSourceSection

      public final SourceSection getSourceSection()
      Retrieves the guest language source code section that is currently assigned to this node.
      Returns:
      the assigned source code section
    • getEncapsulatingSourceSection

      public final SourceSection getEncapsulatingSourceSection()
      Retrieves the guest language source code section that is currently assigned to this node.
      Returns:
      the assigned source code section
    • 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
    • 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
    • adoptChildren

      public final void adoptChildren()
    • 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
    • getParent

      public final Node getParent()
      The current parent node of this node.
      Returns:
      the parent node
    • 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 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
    • replace

      public final <T extends Node> T replace(T newNode)
      Replaces this node with another node. If there is a source section (see 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
    • isReplaceable

      public final boolean isReplaceable()
      Checks if this node is properly adopted by a parent and can be replaced.
      Returns:
      true if it is safe to replace this node.
    • 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
    • onAdopt

      protected void onAdopt()
      Subclasses of Node can implement this method to execute extra functionality when a node is effectively inserted into the AST. The onAdopt callback is called after the node has been effectively inserted, and it is guaranteed to be called only once for any given node.
    • 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
    • getChildren

      public final Iterable<Node> getChildren()
      Iterator over the children of this node.
      Returns:
      the iterator
    • copy

      public Node copy()
      Creates a shallow copy of this node.
      Returns:
      the new copy
    • clone

      @Deprecated protected final Object clone() throws CloneNotSupportedException
      Deprecated.
      This method must never be called. It enforces that Object.clone() is not directly called by subclasses. Use the copy() method instead.
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
    • 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.
    • toString

      public String toString()
      Converts this node to a textual representation useful for debugging.
      Overrides:
      toString in class Object
    • atomic

      public final void atomic(Runnable closure)
    • atomic

      public final <T> T atomic(Callable<T> closure)
    • getDescription

      public String getDescription()
      Returns a user-readable description of the purpose of the Node, or "" if no description is available.
    • getLanguage

      public String getLanguage()
      Returns a string representing the language this node has been implemented for. If the language is unknown, returns "".