diff graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java @ 18485:e3c95cbbb50c

Truffle Instrumentation: major API revision, based around the Probe and Instrument classes; add Instrumentable API for language implementors, with most details automated; reimplemented to handle AST splitting automatically; more JUnit tests.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Sun, 23 Nov 2014 16:07:23 -0800
parents bb9473723904
children 867058575979
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java	Fri Nov 21 13:16:02 2014 +0100
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java	Sun Nov 23 16:07:23 2014 -0800
@@ -27,40 +27,18 @@
 import com.oracle.truffle.api.nodes.*;
 
 /**
- * Implementation of a policy for <em>instrumenting</em> Truffle ASTs with {@link Probe}s at
- * particular nodes by inserting node {@link Wrapper}s.
- * <p>
- * Multiple "node probers" can be added, typically by different tools; the "combined prober" will
- * apply all of them.
- * <p>
- * The current implementation is provisional and does not completely encapsulate everything that
- * needs to be implemented for a particular use-case or set of use-cases. In particular, the AST
- * building code for each language implementation must have hand-coded applications of node probing
- * methods at the desired locations. For the duration of this approach, this must be done for any
- * node that any client tool wishes to probe.
- * <p>
- * A better approach will be to implement such policies as a Truffle {@link NodeVisitor}, but that
- * is not possible at this time.
- * <p>
- * <strong>Disclaimer:</strong> experimental interface under development.
+ * Enables instrumentation by attaching {@linkplain Probe Probes} to some nodes in a (newly created,
+ * not yet executed) AST.
+ *
+ * @see Probe
+ * @see Probe#addProbeListener(com.oracle.truffle.api.instrument.Probe.ProbeListener)
  */
 public interface ASTProber {
 
-    // TODO (mlvdv) This is a provisional interface, more of a marker really
-    // TODO (mlvdv) AST probing should eventually be done with visitors.
+    /**
+     * Walk the AST starting at a node and enable instrumentation at selected nodes by attaching
+     * {@linkplain Probe Probes} to them.
+     */
+    void probeAST(Node node);
 
-    /**
-     * Adds a specification for adding probes at particular kinds of nodes.
-     *
-     * @param nodeProber
-     * @throws IllegalArgumentException if the prober is not applicable to the guest language
-     *             implementation.
-     */
-    void addNodeProber(ASTNodeProber nodeProber) throws IllegalArgumentException;
-
-    /**
-     * Gets a (possibly guest language-specific) {@link ASTNodeProber} that will apply all that have
-     * been added; {@code null} if no instrumentation in AST.
-     */
-    ASTNodeProber getCombinedNodeProber();
 }