Mercurial > hg > truffle

changeset 20909:f96165ecb6f1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/Instrumentation: rename the most recently created kind of Instrument, formerly "ToolNodeblahblah...". It is now defined by SpliceInstrumentListener. This listener allows the client to create an instrument that will *splied* a client-supplied AST fragment directly into a Probe's "instrumentation chain", and this directly into the flow of Truffle execution (with full optimization).
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 13 Apr 2015 15:33:45 -0700
parents f166d264af9f
children 0b2e4d40b683
files graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/ToolNodeInstrumentationTest.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SpliceInstrumentListener.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SplicedNode.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNode.java graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNodeInstrumentListener.java
diffstat 7 files changed, 158 insertions(+), 156 deletions(-) [+]
line wrap: on
line diff
--- a/graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java	Mon Apr 13 15:00:57 2015 -0700
+++ b/graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java	Mon Apr 13 15:33:45 2015 -0700
@@ -212,9 +212,9 @@
         root.adoptChildren();
         Probe probe = result.probe();
         // A listener that could insert a "tool node" into the AST, but which never does.
-        Instrument instrument = Instrument.create(new ToolNodeInstrumentListener() {
+        Instrument instrument = Instrument.create(new SpliceInstrumentListener() {
 
-            public ToolNode getToolNode(Probe p) {
+            public SplicedNode getSpliceNode(Probe p) {
                 return null;
             }
 
@@ -232,10 +232,10 @@
         root.adoptChildren();
         Probe probe = result.probe();
         // A listener that inserts a "tool node" with empty methods into the AST.
-        Instrument instrument = Instrument.create(new ToolNodeInstrumentListener() {
+        Instrument instrument = Instrument.create(new SpliceInstrumentListener() {
 
-            public ToolNode getToolNode(Probe p) {
-                return new ToolNode() {
+            public SplicedNode getSpliceNode(Probe p) {
+                return new SplicedNode() {
                 };
             }
 
--- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/ToolNodeInstrumentationTest.java	Mon Apr 13 15:00:57 2015 -0700
+++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/ToolNodeInstrumentationTest.java	Mon Apr 13 15:33:45 2015 -0700
@@ -58,9 +58,9 @@
         assertEquals(13, callTarget1.call());
 
         // Attach a listener that never actually attaches a node.
-        final Instrument instrument = Instrument.create(new ToolNodeInstrumentListener() {
+        final Instrument instrument = Instrument.create(new SpliceInstrumentListener() {
 
-            public ToolNode getToolNode(Probe p) {
+            public SplicedNode getSpliceNode(Probe p) {
                 return null;
             }
 
@@ -72,10 +72,10 @@
         final int[] count = new int[1];
 
         // Attach a listener that never actually attaches a node.
-        probe.attach(Instrument.create(new ToolNodeInstrumentListener() {
+        probe.attach(Instrument.create(new SpliceInstrumentListener() {
 
-            public ToolNode getToolNode(Probe p) {
-                return new ToolNode() {
+            public SplicedNode getSpliceNode(Probe p) {
+                return new SplicedNode() {
 
                     @Override
                     public void enter(Node node, VirtualFrame vFrame) {
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java	Mon Apr 13 15:00:57 2015 -0700
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java	Mon Apr 13 15:33:45 2015 -0700
@@ -128,15 +128,16 @@
 
     /**
      * Creates an instrument that, when executed the first time in any particular AST location,
-     * invites the tool to provide an AST fragment for attachment/adoption into the running AST.
+     * invites the tool to provide an AST fragment for <em>splicing</em> directly into the running
+     * AST.
      *
-     * @param toolNodeListener a listener for the tool that can request an AST fragment
+     * @param spliceListener a callback to the client that requests an AST node to be splice.
      * @param instrumentInfo instrumentInfo optional description of the instrument's role, useful
      *            for debugging.
      * @return a new instrument, ready for attachment at a probe.
      */
-    public static Instrument create(ToolNodeInstrumentListener toolNodeListener, String instrumentInfo) {
-        return new ToolNodeInstrument(toolNodeListener, instrumentInfo);
+    public static Instrument create(SpliceInstrumentListener spliceListener, String instrumentInfo) {
+        return new SpliceInstrument(spliceListener, instrumentInfo);
     }
 
     // TODO (mlvdv) experimental
@@ -197,6 +198,11 @@
     abstract AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode);
 
     /**
+     * Removes this instrument from an instrument chain.
+     */
+    abstract AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode);
+
+    /**
      * An instrument that propagates events to an instance of {@link SimpleInstrumentListener}.
      */
     private static final class SimpleInstrument extends Instrument {
@@ -276,11 +282,6 @@
     }
 
     /**
-     * Removes this instrument from an instrument chain.
-     */
-    abstract AbstractInstrumentNode removeFromChain(AbstractInstrumentNode instrumentNode);
-
-    /**
      * An instrument that propagates events to an instance of {@link StandardInstrumentListener}.
      */
     private static final class StandardInstrument extends Instrument {
@@ -361,23 +362,24 @@
 
     // TODO (mlvdv) EXPERIMENTAL- UNDER DEVELOPMENT
     /**
-     * An instrument that propagates events to an instance of {@link StandardInstrumentListener}.
+     * An instrument that allows clients to "splice" an AST fragment directly into a Probe's
+     * <em>instrumentation chain</em>, and thus directly into the executing Truffle AST.
      */
-    private static final class ToolNodeInstrument extends Instrument {
+    private static final class SpliceInstrument extends Instrument {
 
         /**
          * Tool-supplied listener for AST events.
          */
-        private final ToolNodeInstrumentListener toolNodeListener;
+        private final SpliceInstrumentListener spliceListener;
 
-        private ToolNodeInstrument(ToolNodeInstrumentListener toolNodeListener, String instrumentInfo) {
+        private SpliceInstrument(SpliceInstrumentListener spliceListener, String instrumentInfo) {
             super(instrumentInfo);
-            this.toolNodeListener = toolNodeListener;
+            this.spliceListener = spliceListener;
         }
 
         @Override
         AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) {
-            return new ToolInstrumentNode(nextNode);
+            return new SpliceInstrumentNode(nextNode);
         }
 
         @Override
@@ -389,7 +391,7 @@
                     return instrumentNode.nextInstrumentNode;
                 }
                 // Match not at the head of the chain; remove it.
-                found = instrumentNode.removeFromChain(ToolNodeInstrument.this);
+                found = instrumentNode.removeFromChain(SpliceInstrument.this);
             }
             if (!found) {
                 throw new IllegalStateException("Couldn't find instrument node to remove: " + this);
@@ -398,25 +400,25 @@
         }
 
         @NodeInfo(cost = NodeCost.NONE)
-        private final class ToolInstrumentNode extends AbstractInstrumentNode {
+        private final class SpliceInstrumentNode extends AbstractInstrumentNode {
 
-            @Child ToolNode toolNode;
+            @Child SplicedNode splicedNode;
 
-            private ToolInstrumentNode(AbstractInstrumentNode nextNode) {
+            private SpliceInstrumentNode(AbstractInstrumentNode nextNode) {
                 super(nextNode);
             }
 
             public void enter(Node node, VirtualFrame vFrame) {
-                if (toolNode == null) {
-                    final ToolNode newToolNode = ToolNodeInstrument.this.toolNodeListener.getToolNode(ToolNodeInstrument.this.probe);
-                    if (newToolNode != null) {
-                        toolNode = newToolNode;
+                if (splicedNode == null) {
+                    final SplicedNode newSplicedNode = SpliceInstrument.this.spliceListener.getSpliceNode(SpliceInstrument.this.probe);
+                    if (newSplicedNode != null) {
+                        splicedNode = newSplicedNode;
                         adoptChildren();
-                        ToolNodeInstrument.this.probe.invalidateProbeUnchanged();
+                        SpliceInstrument.this.probe.invalidateProbeUnchanged();
                     }
                 }
-                if (toolNode != null) {
-                    toolNode.enter(node, vFrame);
+                if (splicedNode != null) {
+                    splicedNode.enter(node, vFrame);
                 }
                 if (nextInstrumentNode != null) {
                     nextInstrumentNode.enter(node, vFrame);
@@ -424,8 +426,8 @@
             }
 
             public void returnVoid(Node node, VirtualFrame vFrame) {
-                if (toolNode != null) {
-                    toolNode.returnVoid(node, vFrame);
+                if (splicedNode != null) {
+                    splicedNode.returnVoid(node, vFrame);
                 }
                 if (nextInstrumentNode != null) {
                     nextInstrumentNode.returnVoid(node, vFrame);
@@ -433,8 +435,8 @@
             }
 
             public void returnValue(Node node, VirtualFrame vFrame, Object result) {
-                if (toolNode != null) {
-                    toolNode.returnValue(node, vFrame, result);
+                if (splicedNode != null) {
+                    splicedNode.returnValue(node, vFrame, result);
                 }
                 if (nextInstrumentNode != null) {
                     nextInstrumentNode.returnValue(node, vFrame, result);
@@ -442,8 +444,8 @@
             }
 
             public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) {
-                if (toolNode != null) {
-                    toolNode.returnExceptional(node, vFrame, exception);
+                if (splicedNode != null) {
+                    splicedNode.returnExceptional(node, vFrame, exception);
                 }
                 if (nextInstrumentNode != null) {
                     nextInstrumentNode.returnExceptional(node, vFrame, exception);
@@ -452,7 +454,7 @@
 
             public String instrumentationInfo() {
                 final String info = getInstrumentInfo();
-                return info != null ? info : toolNodeListener.getClass().getSimpleName();
+                return info != null ? info : spliceListener.getClass().getSimpleName();
             }
         }
     }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SpliceInstrumentListener.java	Mon Apr 13 15:33:45 2015 -0700
@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.api.instrument;
+
+/**
+ * Instrument listener for a tool that works by providing an AST to be <em>spliced</em> directly
+ * into the AST.
+ */
+public interface SpliceInstrumentListener {
+
+    /**
+     * Receive notification that a probed AST node to which the {@link Instrument} is attached is
+     * about to be executed for the first time. This is a lazy opportunity for the tool to
+     * optionally add the root of a newly created AST fragment that will be <em>spliced</em>
+     * directly into the executing AST. The new AST fragment will immediately begin receiving
+     * {@link InstrumentationNode.TruffleEvents}, beginning with the current execution event.
+     * <p>
+     * AST fragments must be written to Truffle conventions. Some of these conventions are
+     * especially important if the fragment is to be fully optimized along with it's new parent AST.
+     * <p>
+     * If this method returns {@code null} then it will be called again the next time the probed
+     * node is about to be executed.
+     * <p>
+     * In some situations, this method will be called more than once for a particular Probe, and a
+     * new instance must be supplied each time. Each instance will be attached at the equivalent
+     * location in clones of the AST, and so should be behave as if equivalent for most purposes.
+     * <p>
+     * In some situations the AST fragment supplied by this method maybe cloned for attachment to
+     * equivalent locations in cloned AST, so care should be taken about any state local to each
+     * instance of the AST fragment.
+     *
+     * @see Instrument
+     */
+    SplicedNode getSpliceNode(Probe probe);
+
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SplicedNode.java	Mon Apr 13 15:33:45 2015 -0700
@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.api.instrument;
+
+import com.oracle.truffle.api.frame.*;
+import com.oracle.truffle.api.nodes.*;
+
+/**
+ * Root of a client-provided AST fragment that can be spliced directly into an executing AST via
+ * {@link Instrument#create(SpliceInstrumentListener, String)}.
+ * <p>
+ * <strong>Note:</strong> Instances of this class will in some situations be cloned by the
+ * instrumentation platform for attachment at equivalent locations in cloned ASTs.
+ */
+public abstract class SplicedNode extends Node implements InstrumentationNode.TruffleEvents, InstrumentationNode {
+
+    public void enter(Node node, VirtualFrame vFrame) {
+    }
+
+    public void returnVoid(Node node, VirtualFrame vFrame) {
+    }
+
+    public void returnValue(Node node, VirtualFrame vFrame, Object result) {
+    }
+
+    public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) {
+    }
+
+    public String instrumentationInfo() {
+        return null;
+    }
+
+}
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNode.java	Mon Apr 13 15:00:57 2015 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,55 +0,0 @@
-/*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-package com.oracle.truffle.api.instrument;
-
-import com.oracle.truffle.api.frame.*;
-import com.oracle.truffle.api.nodes.*;
-
-/**
- * Root of a tool-provided AST fragment that can be attached directly into an executing AST via
- * {@link Instrument#create(ToolNodeInstrumentListener, String)}.
- * <p>
- * <strong>Note:</strong> Instances of this class will in some situations be cloned by the
- * instrumentation platform for attachment at equivalent locations in cloned parent ASTs.
- */
-public abstract class ToolNode extends Node implements InstrumentationNode.TruffleEvents, InstrumentationNode {
-
-    public void enter(Node node, VirtualFrame vFrame) {
-    }
-
-    public void returnVoid(Node node, VirtualFrame vFrame) {
-    }
-
-    public void returnValue(Node node, VirtualFrame vFrame, Object result) {
-    }
-
-    public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) {
-    }
-
-    public String instrumentationInfo() {
-        return null;
-    }
-
-}
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNodeInstrumentListener.java	Mon Apr 13 15:00:57 2015 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,58 +0,0 @@
-/*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-package com.oracle.truffle.api.instrument;
-
-/**
- * Instrument listener for a tool that works by providing an AST to be attached/adopted directly
- * into the AST.
- */
-public interface ToolNodeInstrumentListener {
-
-    /**
-     * Receive notification that a probed AST node to which the {@link Instrument} is attached is
-     * about to be executed for the first time. This is a lazy opportunity for the tool to
-     * optionally add the root of a newly created AST fragment that will be attached/adopted
-     * directly into the executing AST. The new AST fragment will immediately begin receiving
-     * {@link InstrumentationNode.TruffleEvents}, beginning with the current execution event.
-     * <p>
-     * AST fragments must be written to Truffle conventions. Some of these conventions are
-     * especially important if the fragment is to be fully optimized along with it's new parent AST.
-     * <p>
-     * If this method returns {@code null} then it will be called again the next time the probed
-     * node is about to be executed.
-     * <p>
-     * In some situations, this method will be called more than once for a particular Probe, and a
-     * new instance must be supplied each time. Each instance will be attached at the equivalent
-     * location in clones of the AST, and so should be behave as if equivalent for most purposes.
-     * <p>
-     * In some situations the AST fragment supplied by this method maybe cloned for attachment to
-     * equivalent locations in cloned AST, so care should be taken about any state local to each
-     * instance of the AST fragment.
-     *
-     * @see Instrument
-     */
-    ToolNode getToolNode(Probe probe);
-
-}