Mercurial > hg > truffle

changeset 16775:8c606e8053b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Truffle/API test: additional documentation on the new instrumentation tests; move into project with other tests and add an entry in package-info.java
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 11 Aug 2014 10:35:38 -0700
parents 9d55732d0880
children a24beb9c9993
files graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/InstrumentationTest.java graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/WrapperTest.java graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package-info.java
diffstat 3 files changed, 306 insertions(+), 271 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/InstrumentationTest.java	Mon Aug 11 10:35:38 2014 -0700
@@ -0,0 +1,304 @@
+/*
+ * Copyright (c) 2014, 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;
+
+import java.util.*;
+
+import org.junit.*;
+
+import com.oracle.truffle.api.*;
+import com.oracle.truffle.api.frame.*;
+import com.oracle.truffle.api.instrument.*;
+import com.oracle.truffle.api.nodes.*;
+import com.oracle.truffle.api.source.*;
+
+/**
+ * <h3>AST Instrumentation</h3>
+ *
+ * Instrumentation allows the insertion into Truffle ASTs language-specific instances of
+ * {@link Wrapper} that propagate {@link ExecutionEvents} through a {@link Probe} to any instances
+ * of {@link Instrument} that might be attached to the particular probe by tools.
+ * <ol>
+ * <li>Creates a simple add AST</li>
+ * <li>Verifies its structure</li>
+ * <li>"Probes" the add node by adding a {@link Wrapper} and associated {@link Probe}</li>
+ * <li>Attaches a simple {@link Instrument} to the node via its {@link Probe}</li>
+ * <li>Verifies the structure of the probed AST</li>
+ * <li>Verifies the execution of the probed AST</li>
+ * <li>Verifies the results observed by the instrument.</li>
+ * </ol>
+ * To do these tests, several required classes have been implemented in their most basic form, only
+ * implementing the methods necessary for the tests to pass, with stubs elsewhere.
+ */
+public class InstrumentationTest {
+
+    @Test
+    public void test() {
+        // Build a tree
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildNode leftChild = new TestChildNode();
+        TestChildNode rightChild = new TestChildNode();
+        TestSourceSection sourceSection = new TestSourceSection();
+        TestAddNode addNode = new TestAddNode(leftChild, rightChild, sourceSection);
+        TestRootNode rootNode = new TestRootNode(addNode);
+
+        // Have to create a call target before checking parent/child relationships
+        CallTarget target = runtime.createCallTarget(rootNode);
+
+        // Check tree structure
+        Assert.assertEquals(addNode, leftChild.getParent());
+        Assert.assertEquals(addNode, rightChild.getParent());
+        Iterator<Node> iterator = addNode.getChildren().iterator();
+        Assert.assertEquals(leftChild, iterator.next());
+        Assert.assertEquals(rightChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Assert.assertEquals(rootNode, addNode.getParent());
+        iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(addNode, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+
+        // Create another call target, this time with the "probed" add node
+        TestExecutionContext context = new TestExecutionContext();
+        TestWrapper wrapper = new TestWrapper(addNode, context);
+        rootNode = new TestRootNode(wrapper);
+        target = runtime.createCallTarget(rootNode);
+
+        // Check the new tree structure
+        Assert.assertEquals(addNode, leftChild.getParent());
+        Assert.assertEquals(addNode, rightChild.getParent());
+        iterator = addNode.getChildren().iterator();
+        Assert.assertEquals(leftChild, iterator.next());
+        Assert.assertEquals(rightChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Assert.assertEquals(wrapper, addNode.getParent());
+        iterator = wrapper.getChildren().iterator();
+        Assert.assertEquals(addNode, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Assert.assertEquals(rootNode, wrapper.getParent());
+        iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(wrapper, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        result = target.call();
+        Assert.assertEquals(42, result);
+
+        // Create some instruments
+        final TestInstrument instrumentA = new TestInstrument();
+        final TestInstrument instrumentB = new TestInstrument();
+
+        wrapper.getProbe().addInstrument(instrumentA);
+
+        result = target.call();
+        Assert.assertEquals(instrumentA.numInstrumentEnter, 1);
+        Assert.assertEquals(instrumentA.numInstrumentLeave, 1);
+        Assert.assertEquals(instrumentB.numInstrumentEnter, 0);
+        Assert.assertEquals(instrumentB.numInstrumentLeave, 0);
+        Assert.assertEquals(42, result);
+
+        wrapper.getProbe().addInstrument(instrumentB);
+
+        result = target.call();
+        Assert.assertEquals(instrumentA.numInstrumentEnter, 2);
+        Assert.assertEquals(instrumentA.numInstrumentLeave, 2);
+        Assert.assertEquals(instrumentB.numInstrumentEnter, 1);
+        Assert.assertEquals(instrumentB.numInstrumentLeave, 1);
+        Assert.assertEquals(42, result);
+
+        wrapper.getProbe().removeInstrument(instrumentA);
+
+        result = target.call();
+        Assert.assertEquals(instrumentA.numInstrumentEnter, 2);
+        Assert.assertEquals(instrumentA.numInstrumentLeave, 2);
+        Assert.assertEquals(instrumentB.numInstrumentEnter, 2);
+        Assert.assertEquals(instrumentB.numInstrumentLeave, 2);
+        Assert.assertEquals(42, result);
+
+    }
+
+    private class TestRootNode extends RootNode {
+        @Child private RootNode child;
+
+        public TestRootNode(RootNode child) {
+            super(null);
+            this.child = child;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return child.execute(frame);
+        }
+    }
+
+    private class TestAddNode extends RootNode {
+
+        @Child private TestChildNode left;
+        @Child private TestChildNode right;
+
+        public TestAddNode(TestChildNode left, TestChildNode right, TestSourceSection sourceSection) {
+            super(sourceSection);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return left.execute() + right.execute();
+        }
+    }
+
+    private class TestChildNode extends Node {
+
+        public TestChildNode() {
+            super(null);
+        }
+
+        public int execute() {
+            return 21;
+        }
+    }
+
+    /**
+     * The wrapper node class is usually language-specific and inherits from the language-specific
+     * subclass of {@link Node}, not {@RootNode}.
+     */
+    private class TestWrapper extends RootNode implements Wrapper {
+        @Child private RootNode child;
+        private Probe probe;
+
+        public TestWrapper(RootNode child, ExecutionContext context) {
+            this.child = insert(child);
+            this.probe = context.getProbe(child.getSourceSection());
+        }
+
+        public boolean isTaggedAs(SyntaxTag tag) {
+            return false;
+        }
+
+        public Iterable<SyntaxTag> getSyntaxTags() {
+            return null;
+        }
+
+        public Node getChild() {
+            return child;
+        }
+
+        public Probe getProbe() {
+            return probe;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            probe.enter(child, frame);
+            Object result;
+
+            try {
+                result = child.execute(frame);
+                probe.leave(child, frame, result);
+            } catch (Exception e) {
+                probe.leaveExceptional(child, frame, e);
+                throw (e);
+            }
+            return result;
+        }
+    }
+
+    /**
+     * An "empty" description of the source code that might correspond to a particular AST node. The
+     * instrumentation framework tracks probes that have been inserted by their source location,
+     * using this as a key.
+     */
+    private class TestSourceSection implements SourceSection {
+
+        public Source getSource() {
+            return null;
+        }
+
+        public int getStartLine() {
+            return 0;
+        }
+
+        public LineLocation getLineLocation() {
+            return null;
+        }
+
+        public int getStartColumn() {
+            return 0;
+        }
+
+        public int getCharIndex() {
+            return 0;
+        }
+
+        public int getCharLength() {
+            return 0;
+        }
+
+        public int getCharEndIndex() {
+            return 0;
+        }
+
+        public String getIdentifier() {
+            return null;
+        }
+
+        public String getCode() {
+            return null;
+        }
+
+        public String getShortDescription() {
+            return null;
+        }
+
+    }
+
+    private class TestExecutionContext extends ExecutionContext {
+
+        @Override
+        public String getLanguageShortName() {
+            return "test";
+        }
+
+        @Override
+        protected void setSourceCallback(SourceCallback sourceCallback) {
+        }
+
+    }
+
+    private class TestInstrument extends Instrument {
+
+        public int numInstrumentEnter = 0;
+        public int numInstrumentLeave = 0;
+
+        @Override
+        public void enter(Node astNode, VirtualFrame frame) {
+            numInstrumentEnter++;
+        }
+
+        @Override
+        public void leave(Node astNode, VirtualFrame frame, Object result) {
+            numInstrumentLeave++;
+        }
+    }
+
+}
--- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/instrument/WrapperTest.java	Fri Aug 08 15:54:39 2014 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,270 +0,0 @@
-/*
- * Copyright (c) 2012, 2013, 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 java.util.*;
-
-import org.junit.*;
-
-import com.oracle.truffle.api.*;
-import com.oracle.truffle.api.frame.*;
-import com.oracle.truffle.api.instrument.*;
-import com.oracle.truffle.api.nodes.*;
-import com.oracle.truffle.api.source.*;
-
-/**
- * This test does the following:
- * <ol>
- * <li>Creates a simple add AST</li>
- * <li>Verifies its structure</li>
- * <li>Instruments the add node</li>
- * <li>Attaches a simple probe to the instrumented node</li>
- * <li>Verifies the structure of the instrumented AST</li>
- * <li>Verifies the execution of the instrumented AST</li>
- * </ol>
- * To do these tests, several required classes have been implemented in their most basic form, only
- * implementing the methods necessary for the tests to pass, with stubs elsewhere.
- */
-public class WrapperTest {
-
-    @Test
-    public void test() {
-        // Build a tree
-        TruffleRuntime runtime = Truffle.getRuntime();
-        TestChildNode leftChild = new TestChildNode();
-        TestChildNode rightChild = new TestChildNode();
-        TestSourceSection sourceSection = new TestSourceSection();
-        TestAddNode addNode = new TestAddNode(leftChild, rightChild, sourceSection);
-        TestRootNode rootNode = new TestRootNode(addNode);
-
-        // Have to create a call target before checking parent/child relationships
-        CallTarget target = runtime.createCallTarget(rootNode);
-
-        // Check tree structure
-        Assert.assertEquals(addNode, leftChild.getParent());
-        Assert.assertEquals(addNode, rightChild.getParent());
-        Iterator<Node> iterator = addNode.getChildren().iterator();
-        Assert.assertEquals(leftChild, iterator.next());
-        Assert.assertEquals(rightChild, iterator.next());
-        Assert.assertFalse(iterator.hasNext());
-        Assert.assertEquals(rootNode, addNode.getParent());
-        iterator = rootNode.getChildren().iterator();
-        Assert.assertEquals(addNode, iterator.next());
-        Assert.assertFalse(iterator.hasNext());
-        Object result = target.call();
-        Assert.assertEquals(42, result);
-
-        // Add a wrapper
-        TestExecutionContext context = new TestExecutionContext();
-        TestWrapper wrapper = new TestWrapper(addNode, context);
-        rootNode = new TestRootNode(wrapper);
-        target = runtime.createCallTarget(rootNode);
-
-        // Check the new tree structure
-        Assert.assertEquals(addNode, leftChild.getParent());
-        Assert.assertEquals(addNode, rightChild.getParent());
-        iterator = addNode.getChildren().iterator();
-        Assert.assertEquals(leftChild, iterator.next());
-        Assert.assertEquals(rightChild, iterator.next());
-        Assert.assertFalse(iterator.hasNext());
-        Assert.assertEquals(wrapper, addNode.getParent());
-        iterator = wrapper.getChildren().iterator();
-        Assert.assertEquals(addNode, iterator.next());
-        Assert.assertFalse(iterator.hasNext());
-        Assert.assertEquals(rootNode, wrapper.getParent());
-        iterator = rootNode.getChildren().iterator();
-        Assert.assertEquals(wrapper, iterator.next());
-        Assert.assertFalse(iterator.hasNext());
-        result = target.call();
-        Assert.assertEquals(42, result);
-
-        // Add an instrument
-        wrapper.getProbe().addInstrument(new TestInstrument());
-
-        // Check instrument and result
-        result = target.call();
-        Assert.assertEquals(Counter.numInstrumentEnter, 1);
-        Assert.assertEquals(Counter.numInstrumentLeave, 1);
-        Assert.assertEquals(42, result);
-
-    }
-
-    private class TestRootNode extends RootNode {
-        @Child private RootNode child;
-
-        public TestRootNode(RootNode child) {
-            super(null);
-            this.child = child;
-        }
-
-        @Override
-        public Object execute(VirtualFrame frame) {
-            return child.execute(frame);
-        }
-    }
-
-    private class TestAddNode extends RootNode {
-
-        @Child private TestChildNode left;
-        @Child private TestChildNode right;
-
-        public TestAddNode(TestChildNode left, TestChildNode right, TestSourceSection sourceSection) {
-            super(sourceSection);
-            this.left = left;
-            this.right = right;
-        }
-
-        @Override
-        public Object execute(VirtualFrame frame) {
-            return left.execute() + right.execute();
-        }
-    }
-
-    private class TestChildNode extends Node {
-
-        public TestChildNode() {
-            super(null);
-        }
-
-        public int execute() {
-            return 21;
-        }
-    }
-
-    private class TestWrapper extends RootNode implements Wrapper {
-        @Child private RootNode child;
-        private Probe probe;
-
-        public TestWrapper(RootNode child, ExecutionContext context) {
-            this.child = insert(child);
-            this.probe = context.getProbe(child.getSourceSection());
-        }
-
-        public boolean isTaggedAs(SyntaxTag tag) {
-            return false;
-        }
-
-        public Iterable<SyntaxTag> getSyntaxTags() {
-            return null;
-        }
-
-        public Node getChild() {
-            return child;
-        }
-
-        public Probe getProbe() {
-            return probe;
-        }
-
-        @Override
-        public Object execute(VirtualFrame frame) {
-            probe.enter(child, frame);
-            Object result;
-
-            try {
-                result = child.execute(frame);
-                probe.leave(child, frame, result);
-            } catch (Exception e) {
-                probe.leaveExceptional(child, frame, e);
-                throw (e);
-            }
-            return result;
-        }
-    }
-
-    private class TestSourceSection implements SourceSection {
-
-        public Source getSource() {
-            return null;
-        }
-
-        public int getStartLine() {
-            return 0;
-        }
-
-        public LineLocation getLineLocation() {
-            return null;
-        }
-
-        public int getStartColumn() {
-            return 0;
-        }
-
-        public int getCharIndex() {
-            return 0;
-        }
-
-        public int getCharLength() {
-            return 0;
-        }
-
-        public int getCharEndIndex() {
-            return 0;
-        }
-
-        public String getIdentifier() {
-            return null;
-        }
-
-        public String getCode() {
-            return null;
-        }
-
-        public String getShortDescription() {
-            return null;
-        }
-
-    }
-
-    private class TestExecutionContext extends ExecutionContext {
-
-        @Override
-        public String getLanguageShortName() {
-            return "test";
-        }
-
-        @Override
-        protected void setSourceCallback(SourceCallback sourceCallback) {
-
-        }
-
-    }
-
-    private class TestInstrument extends Instrument {
-        @Override
-        public void enter(Node astNode, VirtualFrame frame) {
-            Counter.numInstrumentEnter++;
-        }
-
-        @Override
-        public void leave(Node astNode, VirtualFrame frame, Object result) {
-            Counter.numInstrumentLeave++;
-        }
-    }
-
-    public static class Counter {
-
-        public static int numInstrumentEnter = 0;
-        public static int numInstrumentLeave = 0;
-    }
-}
--- a/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package-info.java	Fri Aug 08 15:54:39 2014 +0200
+++ b/graal/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package-info.java	Mon Aug 11 10:35:38 2014 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, 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
@@ -44,6 +44,7 @@
  * <li>How to use frames and frame slots to store values local to an activation? {@link com.oracle.truffle.api.test.FrameTest}</li>
  * <li>How to use type specialization and speculation for frame slots? {@link com.oracle.truffle.api.test.FrameSlotTypeSpecializationTest}</li>
  * <li>How to use type specialization and speculation for node return values? {@link com.oracle.truffle.api.test.ReturnTypeSpecializationTest}</li>
+ * <li>How to "instrument" an AST with nodes that can provide access to runtime state from external tools {@link com.oracle.truffle.api.test.InstrumentationTest}</li>
  * </ul>
  *
  *