com.oracle.truffle.api.dsl

Class Introspection

java.lang.Object

com.oracle.truffle.api.dsl.Introspection

public final class Introspection
extends Object

Contains introspection utilities for Truffle DSL. The contained utilities are only usable if the operation node is annotated with Introspectable.

Introspection is useful for using testing the node declaration and verifying that particular specializations become active.

Example for using introspection in unit testing:

@Introspectable
abstract static class NegateNode extends Node {

    abstract Object execute(Object o);

    @Specialization(guards = "cachedvalue == value", limit = "1")
    protected static int doInt(int value,
                    @Cached("value") int cachedvalue) {
        return -cachedvalue;
    }

    @Specialization(replaces = "doInt")
    protected static int doGeneric(int value) {
        return -value;
    }
}

public void testUsingIntrospection() {
    NegateNode node = null; // NegateNodeGen.create();
    Introspection.SpecializationInfo info;

    node.execute(1);
    info = Introspection.getSpecialization(node, "doInt");
    assert info.getInstances() == 1;

    node.execute(1);
    info = Introspection.getSpecialization(node, "doInt");
    assert info.getInstances() == 1;

    node.execute(2);
    info = Introspection.getSpecialization(node, "doInt");
    assert info.getInstances() == 0;

    info = Introspection.getSpecialization(node, "doGeneric");
    assert info.getInstances() == 1;
}

Since:

0.22

See Also:

Introspectable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Introspection.Provider Internal marker interface for DSL generated code to access reflection information.
static class	Introspection.SpecializationInfo Represents dynamic introspection information of a specialization of a DSL operation.

Method Summary

Modifier and Type	Method and Description
static Introspection.SpecializationInfo	getSpecialization(Node inlineParent, Node node, String methodName) Like Introspection.getSpecialization(Node, String) but must be used for nodes that were inlined.
static Introspection.SpecializationInfo	getSpecialization(Node node, String methodName) Returns introspection information for the first specialization that matches a given method name.
static List<Introspection.SpecializationInfo>	getSpecializations(Node node) Returns introspection information for all declared specializations as unmodifiable list.
static List<Introspection.SpecializationInfo>	getSpecializations(Node inlineParent, Node node) Like Introspection.getSpecializations(Node) but must be used for nodes that were inlined.
static boolean	isIntrospectable(Node node) Returns true if the given node is introspectable.

Methods inherited from class java.lang.Object

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

Method Detail

isIntrospectable

public static boolean isIntrospectable(Node node)

Returns true if the given node is introspectable. If something is introspectable is determined by if the node is generated by Truffle DSL, if is annotated with Introspectable and if the DSL implementation supports introspection.

Parameters:

node - a DSL generated node

Returns:

true if the given node is introspectable

Since:

0.22

getSpecialization

public static Introspection.SpecializationInfo getSpecialization(Node node,
                                                                 String methodName)

Returns introspection information for the first specialization that matches a given method name. A node must declare at least one specialization and must be annotated with Introspectable otherwise an IllegalArgumentException is thrown. If multiple specializations with the same method name are declared then an undefined specialization is going to be returned. In such cases disambiguate them by renaming the specialzation method name. The returned introspection information is not updated when the state of the given operation node is updated. The implementation of this method might be slow, do not use it in performance critical code.

For a node was inlined use Introspection.getSpecialization(Node, Node, String).

Parameters:

node - a introspectable DSL operation with at least one specialization

methodName - the Java method name of the specialization to introspect

Returns:

introspection info for the method

Since:

0.22

See Also:

example usage

getSpecialization

public static Introspection.SpecializationInfo getSpecialization(Node inlineParent,
                                                                 Node node,
                                                                 String methodName)

Like Introspection.getSpecialization(Node, String) but must be used for nodes that were inlined.

Parameters:

inlineParent - the inlined parent node.

node - a introspectable DSL operation with at least one specialization

methodName - the Java method name of the specialization to introspect

Returns:

introspection info for the method

Since:

23.0

See Also:

example usage

getSpecializations

public static List<Introspection.SpecializationInfo> getSpecializations(Node node)

Returns introspection information for all declared specializations as unmodifiable list. A given node must declare at least one specialization and must be annotated with Introspectable otherwise an IllegalArgumentException is thrown. The returned introspection information is not updated when the state of the given operation node is updated. The implementation of this method might be slow, do not use it in performance critical code.

For a node was inlined use Introspection.getSpecialization(Node, Node, String).

Parameters:

node - a introspectable DSL operation with at least one specialization

Since:

0.22

See Also:

example usage

getSpecializations

public static List<Introspection.SpecializationInfo> getSpecializations(Node inlineParent,
                                                                        Node node)

Like Introspection.getSpecializations(Node) but must be used for nodes that were inlined.

Parameters:

inlineParent - the inlined parent node.

node - a introspectable DSL operation with at least one specialization

Since:

23.0

See Also:

example usage