Mercurial > hg > truffle
changeset 21181:78a4b44420cf
Truffle/Instrumentation: rename the "SplicedNode" Instrument kind to the "ToolEval" instrument kind, along with some redesign based on earlier feedback.
line wrap: on
line diff
--- a/graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java Sat May 02 14:40:49 2015 -0700 +++ b/graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java Sun May 03 21:59:55 2015 -0700 @@ -205,46 +205,53 @@ } @Test - public void constantValueInertSpliceInstrumentListener() { + public void constantValueInertToolEvalNodeFactory() { FrameDescriptor fd = new FrameDescriptor(); AbstractTestNode result = new ConstantTestNode(42); RootTestNode root = new RootTestNode(fd, "constantValue", result); root.adoptChildren(); - Probe probe = result.probe(); - // A listener that could insert a SplicedNode into the AST, but which never does. - Instrument instrument = Instrument.create(new SpliceInstrumentListener() { + Probe testProbe = result.probe(); + // A factory that could insert a ToolEvalNode into the AST, but which never does. + Instrument instrument = Instrument.create(new ToolEvalNodeFactory() { - public SplicedNode getSpliceNode(Probe p) { + public ToolEvalNode createToolEvalNode(Probe probe, Node node) { return null; } - }, null); - probe.attach(instrument); + testProbe.attach(instrument); // It all gets compiled away assertPartialEvalEquals("constant42", root); } @Test - public void constantValueInertSplicedNode() { + public void constantValueInertToolEvalNode() { FrameDescriptor fd = new FrameDescriptor(); - AbstractTestNode result = new ConstantTestNode(42); - RootTestNode root = new RootTestNode(fd, "constantValue", result); - root.adoptChildren(); - Probe probe = result.probe(); - // A listener that inserts a SplicedNode with empty methods into the AST. - Instrument instrument = Instrument.create(new SpliceInstrumentListener() { + AbstractTestNode resultTestNode = new ConstantTestNode(42); + RootTestNode rootTestNode = new RootTestNode(fd, "constantValue", resultTestNode); + rootTestNode.adoptChildren(); + Probe testProbe = resultTestNode.probe(); + // A factory that inserts a ToolEvalNode with empty methods into the instrumentation chain. + Instrument instrument = Instrument.create(new ToolEvalNodeFactory() { - public SplicedNode getSpliceNode(Probe p) { - return new SplicedNode() { + public ToolEvalNode createToolEvalNode(Probe probe, Node node) { + return new ToolEvalNode() { + + public String instrumentationInfo() { + return null; + } + + @Override + public Object executeToolEvalNode(Node n, VirtualFrame frame) { + return null; + } }; } - }, null); - probe.attach(instrument); + testProbe.attach(instrument); // It all gets compiled away. - assertPartialEvalEquals("constant42", root); + assertPartialEvalEquals("constant42", rootTestNode); } @Test
--- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/InstrumentationTestNodes.java Sat May 02 14:40:49 2015 -0700 +++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/InstrumentationTestNodes.java Sun May 03 21:59:55 2015 -0700 @@ -167,17 +167,22 @@ } } - static class TestSplicedCounterNode extends SplicedNode { + static class TestToolEvalCounterNode extends ToolEvalNode { private long count; @Override - public void enter(Node node, VirtualFrame vFrame) { + public Object executeToolEvalNode(Node node, VirtualFrame vFrame) { count++; + return null; } public long getCount() { return count; } + + public String instrumentationInfo() { + return null; + } } }
--- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/SpliceInstrumentTest.java Sat May 02 14:40:49 2015 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,90 +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. - * - * 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.test.instrument; - -import static org.junit.Assert.*; - -import org.junit.*; - -import com.oracle.truffle.api.*; -import com.oracle.truffle.api.instrument.*; -import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestAdditionNode; -import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestRootNode; -import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestValueNode; -import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestSplicedCounterNode; - -/** - * Tests the kind of instrumentation where a client can provide an AST fragment to be - * <em>spliced</em> directly into the AST. - */ -public class SpliceInstrumentTest { - - @Test - public void testSpliceInstrumentListener() { - // Create a simple addition AST - final TruffleRuntime runtime = Truffle.getRuntime(); - final TestValueNode leftValueNode = new TestValueNode(6); - final TestValueNode rightValueNode = new TestValueNode(7); - final TestAdditionNode addNode = new TestAdditionNode(leftValueNode, rightValueNode); - final TestRootNode rootNode = new TestRootNode(addNode); - final CallTarget callTarget1 = runtime.createCallTarget(rootNode); - - // Ensure it executes correctly - assertEquals(13, callTarget1.call()); - - // Probe the addition node - final Probe probe = addNode.probe(); - - assertEquals(13, callTarget1.call()); - - // Attach a null listener; it never actually attaches a node. - final Instrument instrument = Instrument.create(new SpliceInstrumentListener() { - - public SplicedNode getSpliceNode(Probe p) { - return null; - } - - }, null); - probe.attach(instrument); - - assertEquals(13, callTarget1.call()); - - final TestSplicedCounterNode counter = new TestSplicedCounterNode(); - - // Attach a listener that splices an execution counter into the AST. - probe.attach(Instrument.create(new SpliceInstrumentListener() { - - public SplicedNode getSpliceNode(Probe p) { - return counter; - } - - }, null)); - assertEquals(0, counter.getCount()); - - assertEquals(13, callTarget1.call()); - - assertEquals(1, counter.getCount()); - - } - -}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/ToolEvalInstrumentTest.java Sun May 03 21:59:55 2015 -0700 @@ -0,0 +1,89 @@ +/* + * 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. + * + * 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.test.instrument; + +import static org.junit.Assert.*; + +import org.junit.*; + +import com.oracle.truffle.api.*; +import com.oracle.truffle.api.instrument.*; +import com.oracle.truffle.api.nodes.*; +import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestAdditionNode; +import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestRootNode; +import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestValueNode; +import com.oracle.truffle.api.test.instrument.InstrumentationTestNodes.TestToolEvalCounterNode; + +/** + * Tests the kind of instrumentation where a client can provide an AST fragment to be + * <em>spliced</em> directly into the AST. + */ +public class ToolEvalInstrumentTest { + + @Test + public void testSpliceInstrumentListener() { + // Create a simple addition AST + final TruffleRuntime runtime = Truffle.getRuntime(); + final TestValueNode leftValueNode = new TestValueNode(6); + final TestValueNode rightValueNode = new TestValueNode(7); + final TestAdditionNode addNode = new TestAdditionNode(leftValueNode, rightValueNode); + final TestRootNode rootNode = new TestRootNode(addNode); + final CallTarget callTarget1 = runtime.createCallTarget(rootNode); + + // Ensure it executes correctly + assertEquals(13, callTarget1.call()); + + // Probe the addition node + final Probe probe = addNode.probe(); + + assertEquals(13, callTarget1.call()); + + // Attach a null listener; it never actually attaches a node. + final Instrument instrument = Instrument.create(new ToolEvalNodeFactory() { + + public ToolEvalNode createToolEvalNode(Probe p, Node n) { + return null; + } + }, null); + probe.attach(instrument); + + assertEquals(13, callTarget1.call()); + + final TestToolEvalCounterNode counter = new TestToolEvalCounterNode(); + + // Attach a listener that splices an execution counter into the AST. + probe.attach(Instrument.create(new ToolEvalNodeFactory() { + + public ToolEvalNode createToolEvalNode(Probe p, Node n) { + return counter; + } + }, null)); + assertEquals(0, counter.getCount()); + + assertEquals(13, callTarget1.call()); + + assertEquals(1, counter.getCount()); + + } + +}
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Sat May 02 14:40:49 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java Sun May 03 21:59:55 2015 -0700 @@ -103,10 +103,11 @@ public abstract class Instrument { /** - * Creates an instrument that will route execution events to a listener. + * Creates a <em>Simple Instrument</em>: this Instrument routes execution events to a + * client-provided listener. * - * @param listener a minimal listener for event generated by the instrument. - * @param instrumentInfo optional description of the instrument's role, useful for debugging. + * @param listener a listener for execution events + * @param instrumentInfo optional description of the instrument's role, intended for debugging. * @return a new instrument, ready for attachment at a probe */ public static Instrument create(SimpleInstrumentListener listener, String instrumentInfo) { @@ -114,12 +115,11 @@ } /** - * Creates an instrument that will route execution events to a listener, along with access to - * internal execution state. + * Creates a <em>Standard Instrument</em>: this Instrument routes execution events, together + * with access to Truffle execution state, to a client-provided listener. * - * @param standardListener a listener for event generated by the instrument that provides access - * to internal execution state - * @param instrumentInfo optional description of the instrument's role, useful for debugging. + * @param standardListener a listener for execution events and execution state + * @param instrumentInfo optional description of the instrument's role, intended for debugging. * @return a new instrument, ready for attachment at a probe */ public static Instrument create(StandardInstrumentListener standardListener, String instrumentInfo) { @@ -127,17 +127,16 @@ } /** - * Creates an instrument that, when executed the first time in any particular AST location, - * invites the tool to provide an AST fragment for <em>splicing</em> directly into the running - * AST. + * Creates a <em>Tool Eval Instrument</em>: this Instrument executes efficiently, subject to + * full Truffle optimization, a client-provided AST fragment every time the Probed node is + * entered. * - * @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. + * @param toolEvalNodeFactory provider of AST fragments on behalf of the client + * @param instrumentInfo optional description of the instrument's role, intended for debugging. + * @return a new instrument, ready for attachment at a probe */ - public static Instrument create(SpliceInstrumentListener spliceListener, String instrumentInfo) { - return new SpliceInstrument(spliceListener, instrumentInfo); + public static Instrument create(ToolEvalNodeFactory toolEvalNodeFactory, String instrumentInfo) { + return new ToolEvalInstrument(toolEvalNodeFactory, instrumentInfo); } // TODO (mlvdv) experimental @@ -165,7 +164,16 @@ } /** - * Removes this instrument from the probe to which it attached and renders the instrument inert. + * Gets the {@link Probe} to which this Instrument is currently attached: {@code null} if not + * yet attached to a Probe or if this Instrument has been {@linkplain #dispose() disposed}. + */ + public Probe getProbe() { + return probe; + } + + /** + * Removes this Instrument from the Probe to which it attached and renders this Instrument + * inert. * * @throws IllegalStateException if this instrument has already been disposed */ @@ -176,14 +184,14 @@ if (probe != null) { // It's attached probe.disposeInstrument(this); + probe = null; } this.isDisposed = true; } - Probe getProbe() { - return probe; - } - + /** + * For internal implementation only. + */ void setAttachedTo(Probe probe) { this.probe = probe; } @@ -239,6 +247,9 @@ return instrumentNode; } + /** + * Node that implements a {@link SimpleInstrument} in a particular AST. + */ @NodeInfo(cost = NodeCost.NONE) private final class SimpleInstrumentNode extends AbstractInstrumentNode { @@ -318,6 +329,9 @@ return instrumentNode; } + /** + * Node that implements a {@link StandardInstrument} in a particular AST. + */ @NodeInfo(cost = NodeCost.NONE) private final class StandardInstrumentNode extends AbstractInstrumentNode { @@ -360,26 +374,27 @@ } } - // TODO (mlvdv) EXPERIMENTAL- UNDER DEVELOPMENT /** - * 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. + * An instrument that allows clients to provide an AST fragment to be executed directly from + * within a Probe's <em>instrumentation chain</em>, and thus directly in the executing Truffle + * AST with potential for full optimization. */ - private static final class SpliceInstrument extends Instrument { + private static final class ToolEvalInstrument extends Instrument { /** - * Tool-supplied listener for AST events. + * Client-provided supplier of new node instances to attach. */ - private final SpliceInstrumentListener spliceListener; + private final ToolEvalNodeFactory toolEvalNodeFactory; - private SpliceInstrument(SpliceInstrumentListener spliceListener, String instrumentInfo) { + private ToolEvalInstrument(ToolEvalNodeFactory toolEvalNodeFactory, String instrumentInfo) { super(instrumentInfo); - this.spliceListener = spliceListener; + this.toolEvalNodeFactory = toolEvalNodeFactory; + } @Override AbstractInstrumentNode addToChain(AbstractInstrumentNode nextNode) { - return new SpliceInstrumentNode(nextNode); + return new ToolEvalNodeInstrumentNode(nextNode); } @Override @@ -391,7 +406,7 @@ return instrumentNode.nextInstrumentNode; } // Match not at the head of the chain; remove it. - found = instrumentNode.removeFromChain(SpliceInstrument.this); + found = instrumentNode.removeFromChain(ToolEvalInstrument.this); } if (!found) { throw new IllegalStateException("Couldn't find instrument node to remove: " + this); @@ -399,26 +414,30 @@ return instrumentNode; } + /** + * Node that implements a {@link ToolEvalInstrument} in a particular AST. + */ @NodeInfo(cost = NodeCost.NONE) - private final class SpliceInstrumentNode extends AbstractInstrumentNode { + private final class ToolEvalNodeInstrumentNode extends AbstractInstrumentNode { - @Child SplicedNode splicedNode; + @Child ToolEvalNode toolEvalNode; - private SpliceInstrumentNode(AbstractInstrumentNode nextNode) { + private ToolEvalNodeInstrumentNode(AbstractInstrumentNode nextNode) { super(nextNode); } public void enter(Node node, VirtualFrame vFrame) { - if (splicedNode == null) { - final SplicedNode newSplicedNode = SpliceInstrument.this.spliceListener.getSpliceNode(SpliceInstrument.this.probe); - if (newSplicedNode != null) { - splicedNode = newSplicedNode; + if (toolEvalNode == null) { + final ToolEvalNode newToolEvalNodeNode = ToolEvalInstrument.this.toolEvalNodeFactory.createToolEvalNode(ToolEvalInstrument.this.probe, node); + if (newToolEvalNodeNode != null) { + toolEvalNode = newToolEvalNodeNode; adoptChildren(); - SpliceInstrument.this.probe.invalidateProbeUnchanged(); + ToolEvalInstrument.this.probe.invalidateProbeUnchanged(); } } - if (splicedNode != null) { - splicedNode.enter(node, vFrame); + if (toolEvalNode != null) { + // TODO (mlvdv) should report exception ; non-trivial architectural change + toolEvalNode.executeToolEvalNode(node, vFrame); } if (nextInstrumentNode != null) { nextInstrumentNode.enter(node, vFrame); @@ -426,27 +445,18 @@ } public void returnVoid(Node node, VirtualFrame vFrame) { - if (splicedNode != null) { - splicedNode.returnVoid(node, vFrame); - } if (nextInstrumentNode != null) { nextInstrumentNode.returnVoid(node, vFrame); } } public void returnValue(Node node, VirtualFrame vFrame, Object result) { - if (splicedNode != null) { - splicedNode.returnValue(node, vFrame, result); - } if (nextInstrumentNode != null) { nextInstrumentNode.returnValue(node, vFrame, result); } } public void returnExceptional(Node node, VirtualFrame vFrame, Exception exception) { - if (splicedNode != null) { - splicedNode.returnExceptional(node, vFrame, exception); - } if (nextInstrumentNode != null) { nextInstrumentNode.returnExceptional(node, vFrame, exception); } @@ -454,7 +464,7 @@ public String instrumentationInfo() { final String info = getInstrumentInfo(); - return info != null ? info : spliceListener.getClass().getSimpleName(); + return info != null ? info : toolEvalNodeFactory.getClass().getSimpleName(); } } }
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/InstrumentationException.java Sun May 03 21:59:55 2015 -0700 @@ -0,0 +1,35 @@ +/* + * 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; + +public class InstrumentationException extends Exception { + + public InstrumentationException(RuntimeException ex) { + super(ex); + } + + private static final long serialVersionUID = 447857066220935502L; + +}
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ProbeNode.java Sat May 02 14:40:49 2015 -0700 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ProbeNode.java Sun May 03 21:59:55 2015 -0700 @@ -200,6 +200,13 @@ } /** + * Gets the guest-language AST node to which this Probe is attached. + */ + Node getProbedNode() { + return ((WrapperNode) this.getParent()).getChild(); + } + + /** * Adds an {@link AbstractInstrumentNode} to this chain. */ @TruffleBoundary
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SpliceInstrumentListener.java Sat May 02 14:40:49 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 <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); - -}
--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SplicedNode.java Sat May 02 14:40:49 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 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; - } - -}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolEvalNode.java Sun May 03 21:59:55 2015 -0700 @@ -0,0 +1,51 @@ +/* + * 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 executed efficiently, subject to full Truffle + * optimization, by a {@linkplain Instrument#create(ToolEvalNodeFactory, String) Tool Eval + * Instrument}. + * + * @see Instrument + * @see ToolEvalNodeFactory + * @see ToolEvalResultListener + */ +public abstract class ToolEvalNode extends Node implements InstrumentationNode { + + /** + * Executes this AST fragment on behalf of a client {@link Instrument}, just before the + * guest-language AST node to which the {@link Probe} holding the Instrument is executed. + * + * @param node the guest-language AST node to which the host Instrument's Probe is attached + * @param vFrame execution frame at the guest-language AST node + * @return the result of this AST fragment's execution + */ + public abstract Object executeToolEvalNode(Node node, VirtualFrame vFrame); + +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolEvalNodeFactory.java Sun May 03 21:59:55 2015 -0700 @@ -0,0 +1,51 @@ +/* + * 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.nodes.*; + +/** + * Creator of {@linkplain ToolEvalNode AST fragments} suitable for efficient execution, subject to + * full Truffle optimization, by a {@linkplain Instrument#create(ToolEvalNodeFactory, String) Tool + * Eval Instrument}. + * + * @see Instrument + * @see ToolEvalNode + */ +public interface ToolEvalNodeFactory { + + /** + * Provider of {@linkplain ToolEvalNode AST fragment} instances for efficient execution via + * instrumentation, subject to full Truffle optimization, at a {@linkplain Probe Probed} site in + * a guest-language AST. + * + * @param probe the Probe to which the Instrument requesting the AST fragment is attached + * @param node the guest-language AST location that is the context in which the requesting + * Instrument must execute the AST fragment. + * @return a newly created AST fragment suitable for execution, via instrumentation, in the + * execution context of the specified guest-language AST site. + */ + ToolEvalNode createToolEvalNode(Probe probe, Node node); +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolEvalResultListener.java Sun May 03 21:59:55 2015 -0700 @@ -0,0 +1,64 @@ +/* + * 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.*; + +/** + * Listener for receiving the result a client-provided {@linkplain ToolEvalNode AST fragment}, when + * executed by a {@linkplain Instrument#create(ToolEvalNodeFactory, String) Tool Eval Instrument}. + * + * @see Instrument + * @see ToolEvalNode + * @see ToolEvalNodeFactory + */ +public interface ToolEvalResultListener { + + /** + * Notifies listener that a client-provided {@linkplain ToolEvalNode AST fragment} has been + * executed by a {@linkplain Instrument#create(ToolEvalNodeFactory, String) Tool Eval + * Instrument} with the specified result, possibly {@code null}. + * + * @param node the guest-language AST node to which the host Instrument's {@link Probe} is + * attached + * @param vFrame execution frame at the guest-language AST node + * @param result the result of this AST fragment's execution + */ + void notifyToolEvalResult(Node node, VirtualFrame vFrame, Object result); + + /** + * Notifies listener that execution of client-provided {@linkplain ToolEvalNode AST fragment} + * filed during execution by a @linkplain Instrument#create(ToolEvalNodeFactory, String) Tool + * Eval Instrument}. + * + * @param node the guest-language AST node to which the host Instrument's {@link Probe} is + * attached + * @param vFrame execution frame at the guest-language AST node + * @param ex the exception + */ + void notifyToolEvalFailure(Node node, VirtualFrame vFrame, RuntimeException ex); + +}