com.oracle.truffle.api.nodes

Class BlockNode<T extends Node>

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.nodes.BlockNode<T>

Type Parameters:

T - the type of the block element node

All Implemented Interfaces:

NodeInterface, Cloneable

public abstract class BlockNode<T extends Node>
extends Node

Represents a standard node for guest language blocks. Using standard blocks in a guest language is not strictly necessary, but recommended as it allows the optimizing runtime to split compilation of very big methods into multiple compilation units. Block nodes may be executed with a customizable argument to resume the execution at a particular location.

Elements are executed using the BlockNode.ElementExecutor provided when creating the block node. When a block is executed then all elements are executed using executeVoid except the last element which will be executed using the typed execute method also used to execute the block node. This allows to implement boxing elimination of the return value of blocks in the interpreter. For example, if executeInt is invoked on the block , then all elements except the last one is executed using executeVoid, but the last one with executeInt.

The optimizing runtime may decide to group elements of a block into multiple block compilation units. This may happen if the block is too big to be compiled with a single compilation unit. If the compilation final state of an element is changed, or a node is replaced only the compilation unit of the current block is invalidated and not all compilations units of a block. Therefore, no compilation final assumptions must be taken between elements of a block.

Simple Usage:

The following example shows how a language with untyped execute methods, but with blocks that return values would use the block node.

// language base node
abstract class LanguageNode extends Node {

    public abstract Object execute(VirtualFrame frame);

}

final class LanguageBlockNode extends LanguageNode
                implements BlockNode.ElementExecutor<LanguageNode> {

    @Child private BlockNode<LanguageNode> block;

    LanguageBlockNode(LanguageNode[] elements) {
        this.block = BlockNode.create(elements, this);
    }

    @Override
    public void executeVoid(VirtualFrame frame, LanguageNode node,
                    int index, int arg) {
        node.execute(frame);
    }

    @Override
    public Object executeGeneric(VirtualFrame frame, LanguageNode node,
                    int index, int arg) {
        return node.execute(frame);
    }

    @Override
    public Object execute(VirtualFrame frame) {
        return block.executeGeneric(frame, 0);
    }
}

Resumable Usage:

The following example shows how the block node can be used to implement resumable blocks, e.g. for generator implementations:

final class YieldException extends ControlFlowException {

    final Object result;

    YieldException(Object result) {
        this.result = result;
    }

}

final class ResumableBlockNode extends LanguageNode
                implements BlockNode.ElementExecutor<LanguageNode> {

    @CompilerDirectives.CompilationFinal private FrameSlot indexSlot;
    @Child private BlockNode<LanguageNode> block;

    ResumableBlockNode(LanguageNode[] elements) {
        this.block = BlockNode.create(elements, this);
    }

    @Override
    public Object execute(VirtualFrame frame) {
        frame.setInt(getIndexSlot(), 0);
        return block.executeGeneric(frame, 0);
    }

    // Called if the resumable block needs to be
    // resumed later on after a yield.
    public void resume(VirtualFrame frame) {
        getIndexSlot();
        int startIndex;
        try {
            startIndex = frame.getInt(getIndexSlot());
        } catch (FrameSlotTypeException e) {
            // should not happen because the first time
            // the block must be called using execute
            throw new AssertionError();
        }
        block.executeGeneric(frame, startIndex);
    }

    @Override
    public void executeVoid(VirtualFrame frame, LanguageNode node,
                    int elementIndex, int startIndex) {
        executeGeneric(frame, node, elementIndex, startIndex);
    }

    @Override
    public Object executeGeneric(VirtualFrame frame, LanguageNode node,
                    int elementIndex, int startIndex) {
        if (elementIndex >= startIndex) {
            try {
                return node.execute(frame);
            } catch (YieldException e) {
                // store index to be able to resume later
                frame.setInt(getIndexSlot(), elementIndex);
                return e.result;
            }
        } else {
            CompilerDirectives.transferToInterpreterAndInvalidate();
            throw new AssertionError("Invalid start index");
        }
    }

    private FrameSlot getIndexSlot() {
        FrameSlot slot = this.indexSlot;
        if (slot == null) {
            CompilerDirectives.transferToInterpreterAndInvalidate();
            FrameDescriptor fd = getRootNode().getFrameDescriptor();
            this.indexSlot = slot = fd.findOrAddFrameSlot(this);
        }
        return slot;
    }

}

Since:

19.3

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BlockNode.ElementExecutor<T extends Node> Represents a contract how block element nodes can be executed.

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

Node.Child, Node.Children

Field Summary

Fields

Modifier and Type	Field and Description
static int	NO_ARGUMENT Use when no argument is needed for the block node.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BlockNode(T[] elements) Internal constructor for implementations.

Method Summary

Modifier and Type	Method and Description
static <T extends Node> BlockNode<T>	create(T[] elements, BlockNode.ElementExecutor<T> executor) Creates a new block node.
abstract boolean	executeBoolean(VirtualFrame frame, int argument) Executes the block and returns a boolean value.
abstract byte	executeByte(VirtualFrame frame, int argument) Executes the block and returns a byte value.
abstract char	executeChar(VirtualFrame frame, int argument) Executes the block and returns a char value.
abstract double	executeDouble(VirtualFrame frame, int argument) Executes the block and returns a double value.
abstract float	executeFloat(VirtualFrame frame, int argument) Executes the block and returns a float value.
abstract Object	executeGeneric(VirtualFrame frame, int argument) Executes the block and returns a generic value.
abstract int	executeInt(VirtualFrame frame, int argument) Executes the block and returns an int value.
abstract long	executeLong(VirtualFrame frame, int argument) Executes the block and returns a long value.
abstract short	executeShort(VirtualFrame frame, int argument) Executes the block and returns a short value.
abstract void	executeVoid(VirtualFrame frame, int argument) Executes the block and returns no value.
NodeCost	getCost() Block nodes always have NodeCost.NONE.
T[]	getElements() Returns the elements of the block node.

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

accept, adoptChildren, atomic, atomic, copy, deepCopy, getChildren, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, lookupContextReference, lookupLanguageReference, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString

Methods inherited from class java.lang.Object

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

Field Detail

NO_ARGUMENT

public static final int NO_ARGUMENT

Use when no argument is needed for the block node.

Since:

19.3

See Also:

Constant Field Values

Constructor Detail

BlockNode

protected BlockNode(T[] elements)

Internal constructor for implementations. Do not use.

Since:

19.3

Method Detail

executeVoid

public abstract void executeVoid(VirtualFrame frame,
                                 int argument)

Executes the block and returns no value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block.

Parameters:

frame - the frame to execute the block in.

argument - a custom argument that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Since:

19.3

executeGeneric

public abstract Object executeGeneric(VirtualFrame frame,
                                      int argument)

Executes the block and returns a generic value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeGeneric(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Since:

19.3

executeByte

public abstract byte executeByte(VirtualFrame frame,
                                 int argument)
                          throws UnexpectedResultException

Executes the block and returns a byte value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeByte(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeShort

public abstract short executeShort(VirtualFrame frame,
                                   int argument)
                            throws UnexpectedResultException

Executes the block and returns a short value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeShort(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeInt

public abstract int executeInt(VirtualFrame frame,
                               int argument)
                        throws UnexpectedResultException

Executes the block and returns an int value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeInt(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeChar

public abstract char executeChar(VirtualFrame frame,
                                 int argument)
                          throws UnexpectedResultException

Executes the block and returns a char value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeChar(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeFloat

public abstract float executeFloat(VirtualFrame frame,
                                   int argument)
                            throws UnexpectedResultException

Executes the block and returns a float value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeFloat(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeDouble

public abstract double executeDouble(VirtualFrame frame,
                                     int argument)
                              throws UnexpectedResultException

Executes the block and returns a double value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeDouble(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeLong

public abstract long executeLong(VirtualFrame frame,
                                 int argument)
                          throws UnexpectedResultException

Executes the block and returns a long value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeLong(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

executeBoolean

public abstract boolean executeBoolean(VirtualFrame frame,
                                       int argument)
                                throws UnexpectedResultException

Executes the block and returns a boolean value. The block implementation calls BlockNode.ElementExecutor.executeVoid(VirtualFrame, Node, int, int) for all elements of the block except the last element. The last element is executed using BlockNode.ElementExecutor.executeBoolean(VirtualFrame, Node, int, int).

Parameters:

frame - the frame to execute the block in.

argument - a custom value that is forwarded to the executor as is. If no argument is needed then BlockNode.NO_ARGUMENT should be used.

Throws:

UnexpectedResultException

Since:

19.3

getElements

public final T[] getElements()

Returns the elements of the block node. Elements of block nodes are provided using BlockNode.create(Node[], ElementExecutor).

Since:

19.3

getCost

public final NodeCost getCost()

Block nodes always have NodeCost.NONE. 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.

Overrides:

getCost in class Node

Since:

19.3

create

public static <T extends Node> BlockNode<T> create(T[] elements,
                                                   BlockNode.ElementExecutor<T> executor)

Creates a new block node. The elements array of the block node must not be empty or an IllegalArgumentException is thrown. Elements of a block must at least extend Node. An executor must be provided that allows the block node implementation to execute the block elements. The executor must not be null.

Since:

19.3