Mercurial > hg > truffle

diff graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java @ 15605:bb9473723904

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: - Merge instrumentation support into the general execution context; remove separate Instrumentation interface and implementation - Generalize the ?tagging? mechanism for extensibility: the enum PhylumTag is now an interface, and the standard tags moved to the new enum StandardTag - A new ?trap? mechanism interrupts program execution at any probed node holding a specified PhylumTag; this replaces some other special-purpose code. - Refine several interface by factoring out callback methods and simplifying collaboration among key implementation classes.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 12 May 2014 20:17:25 -0700
parents 0c6d8a08e31b
children e3c95cbbb50c
line wrap: on
line diff
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java	Fri May 02 16:12:07 2014 -0700
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ASTProber.java	Mon May 12 20:17:25 2014 -0700
@@ -24,10 +24,24 @@
  */
 package com.oracle.truffle.api.instrument;
 
+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.
  */
 public interface ASTProber {
@@ -35,10 +49,18 @@
     // TODO (mlvdv) This is a provisional interface, more of a marker really
     // TODO (mlvdv) AST probing should eventually be done with visitors.
 
-    void addNodeProber(ASTNodeProber nodeProber);
+    /**
+     * 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 prober that applies all added {@link ASTNodeProber}s.
+     * 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();
 }