Package 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();
    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:

  • Method Details

    • 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 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:

    • getSpecialization

      public static Introspection.SpecializationInfo getSpecialization(Node inlineParent, Node node, String methodName)
      Like 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:

    • 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 getSpecialization(Node, Node, String).

      Parameters:
      node - a introspectable DSL operation with at least one specialization
      Since:
      0.22
      See Also:

    • getSpecializations

      public static List<Introspection.SpecializationInfo> getSpecializations(Node inlineParent, Node node)
      Like 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: