# HG changeset patch # User Michael Van De Vanter # Date 1428964425 25200 # Node ID f96165ecb6f1c1415cb5a0bf7e7beb7046b20795 # Parent f166d264af9fa2f8c82ad0ad2f5e1b18889f298f 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). diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.graal.truffle.test/src/com/oracle/graal/truffle/test/InstrumentationPartialEvaluationTest.java --- 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() { }; } diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/ToolNodeInstrumentationTest.java --- 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) { diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/Instrument.java --- 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 splicing 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 + * instrumentation chain, 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(); } } } diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SpliceInstrumentListener.java --- /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 spliced 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 spliced + * directly into the executing AST. The new AST fragment will immediately begin receiving + * {@link InstrumentationNode.TruffleEvents}, beginning with the current execution event. + *

+ * 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. + *

+ * If this method returns {@code null} then it will be called again the next time the probed + * node is about to be executed. + *

+ * 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. + *

+ * 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); + +} diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/SplicedNode.java --- /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)}. + *

+ * Note: 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; + } + +} diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNode.java --- 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)}. - *

- * Note: 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; - } - -} diff -r f166d264af9f -r f96165ecb6f1 graal/com.oracle.truffle.api/src/com/oracle/truffle/api/instrument/ToolNodeInstrumentListener.java --- 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. - *

- * 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. - *

- * If this method returns {@code null} then it will be called again the next time the probed - * node is about to be executed. - *

- * 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. - *

- * 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); - -}