--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ArgumentsTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,108 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Passing Arguments</h3>
+ *
+ * <p>
+ * When invoking a call target with {@link CallTarget#call(Object[])}, arguments can be passed. A
+ * Truffle node can access the arguments passed into the Truffle method by using
+ * {@link VirtualFrame#getArguments}.
+ * </p>
+ *
+ * <p>
+ * The arguments class should only contain fields that are declared as final. This allows the
+ * Truffle runtime to improve optimizations around guest language method calls. Also, the arguments
+ * object array must never be stored into a field. It should be created immediately before invoking
+ * {@link CallTarget#call(Object[])} and no longer be accessed afterwards.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.FrameTest} .
+ * </p>
+ */
+public class ArgumentsTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestRootNode rootNode = new TestRootNode(new TestArgumentNode[]{new TestArgumentNode(0), new TestArgumentNode(1)});
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Object result = target.call(new Object[]{20, 22});
+        Assert.assertEquals(42, result);
+    }
+
+    private static class TestRootNode extends RootNode {
+
+        @Children private final TestArgumentNode[] children;
+
+        TestRootNode(TestArgumentNode[] children) {
+            super(TestingLanguage.class, null, null);
+            this.children = children;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            int sum = 0;
+            for (int i = 0; i < children.length; ++i) {
+                sum += children[i].execute(frame);
+            }
+            return sum;
+        }
+    }
+
+    private static class TestArgumentNode extends Node {
+
+        private final int index;
+
+        TestArgumentNode(int index) {
+            super(null);
+            this.index = index;
+        }
+
+        int execute(VirtualFrame frame) {
+            return (Integer) frame.getArguments()[index];
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/CallTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,100 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Calling Another Tree</h3>
+ *
+ * <p>
+ * A guest language implementation can create multiple call targets using the
+ * {@link TruffleRuntime#createCallTarget(RootNode)} method. Those call targets can be passed around
+ * as normal Java objects and used for calling guest language methods.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.ArgumentsTest}.
+ * </p>
+ */
+public class CallTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        CallTarget foo = runtime.createCallTarget(new ConstantRootNode(20));
+        CallTarget bar = runtime.createCallTarget(new ConstantRootNode(22));
+        CallTarget main = runtime.createCallTarget(new DualCallNode(foo, bar));
+        Object result = main.call();
+        Assert.assertEquals(42, result);
+    }
+
+    class DualCallNode extends RootNode {
+
+        private final CallTarget firstTarget;
+        private final CallTarget secondTarget;
+
+        DualCallNode(CallTarget firstTarget, CallTarget secondTarget) {
+            super(TestingLanguage.class, null, null);
+            this.firstTarget = firstTarget;
+            this.secondTarget = secondTarget;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return ((Integer) firstTarget.call()) + ((Integer) secondTarget.call());
+        }
+    }
+
+    class ConstantRootNode extends RootNode {
+
+        private final int value;
+
+        public ConstantRootNode(int value) {
+            super(TestingLanguage.class, null, null);
+            this.value = value;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return value;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ChildNodeTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,114 @@
+/*
+ * 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;
+
+import java.util.Iterator;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.Node.Child;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Creating a Child Node</h3>
+ *
+ * <p>
+ * Child nodes are stored in the class of the parent node in fields that are marked with the
+ * {@link Child} annotation. The {@link Node#getParent()} method allows access to this field. Every
+ * node also provides the ability to iterate over its children using {@link Node#getChildren()}.
+ * </p>
+ *
+ * <p>
+ * A child node field must be declared private and non-final. It may only be assigned in the
+ * constructor of the parent node. For changing the structure of the tree at run time, the method
+ * {@link Node#replace(Node)} must be used (see {@link ReplaceTest}).
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at
+ * {@link com.oracle.truffle.api.ChildrenNodesTest}.
+ * </p>
+ */
+public class ChildNodeTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildNode leftChild = new TestChildNode();
+        TestChildNode rightChild = new TestChildNode();
+        TestRootNode rootNode = new TestRootNode(leftChild, rightChild);
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Assert.assertEquals(rootNode, leftChild.getParent());
+        Assert.assertEquals(rootNode, rightChild.getParent());
+        Iterator<Node> iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(leftChild, iterator.next());
+        Assert.assertEquals(rightChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Child private TestChildNode left;
+        @Child private TestChildNode right;
+
+        public TestRootNode(TestChildNode left, TestChildNode right) {
+            super(TestingLanguage.class, null, null);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return left.execute() + right.execute();
+        }
+    }
+
+    class TestChildNode extends Node {
+
+        public TestChildNode() {
+            super(null);
+        }
+
+        public int execute() {
+            return 21;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ChildrenNodesTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,158 @@
+/*
+ * 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;
+
+import java.util.Iterator;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Creating an Array of Children Nodes</h3>
+ *
+ * <p>
+ * An array of children nodes can be used as a field in a parent node. The field has to be annotated
+ * with {@link com.oracle.truffle.api.nodes.Node.Children} and must be declared private and final.
+ * Before assigning the field in the parent node constructor, {@link Node#adoptChildren} must be
+ * called in order to update the parent pointers in the child nodes. After filling the array with
+ * its first values, it must never be changed. It is only possible to call {@link Node#replace} on a
+ * child node.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.FinalFieldTest}
+ * .
+ * </p>
+ */
+public class ChildrenNodesTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildNode firstChild = new TestChildNode();
+        TestChildNode secondChild = new TestChildNode();
+        TestRootNode rootNode = new TestRootNode(new TestChildNode[]{firstChild, secondChild});
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Assert.assertEquals(rootNode, firstChild.getParent());
+        Assert.assertEquals(rootNode, secondChild.getParent());
+        Iterator<Node> iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(firstChild, iterator.next());
+        Assert.assertEquals(secondChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Children private final TestChildNode[] children;
+
+        public TestRootNode(TestChildNode[] children) {
+            super(TestingLanguage.class, null, null);
+            this.children = children;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            int sum = 0;
+            for (int i = 0; i < children.length; ++i) {
+                sum += children[i].execute();
+            }
+            return sum;
+        }
+    }
+
+    class TestChildNode extends Node {
+
+        public TestChildNode() {
+            super(null);
+        }
+
+        public int execute() {
+            return 21;
+        }
+    }
+
+    @Test
+    public void testMultipleChildrenFields() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildNode firstChild = new TestChildNode();
+        TestChildNode secondChild = new TestChildNode();
+        TestChildNode thirdChild = new TestChildNode();
+        TestChildNode forthChild = new TestChildNode();
+        TestRootNode rootNode = new TestRoot2Node(new TestChildNode[]{firstChild, secondChild}, new TestChildNode[]{thirdChild, forthChild});
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Assert.assertEquals(rootNode, firstChild.getParent());
+        Assert.assertEquals(rootNode, secondChild.getParent());
+        Assert.assertEquals(rootNode, thirdChild.getParent());
+        Assert.assertEquals(rootNode, forthChild.getParent());
+        Iterator<Node> iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(firstChild, iterator.next());
+        Assert.assertEquals(secondChild, iterator.next());
+        Assert.assertEquals(thirdChild, iterator.next());
+        Assert.assertEquals(forthChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(2 * 42, result);
+    }
+
+    class TestRoot2Node extends TestRootNode {
+        @Children private final TestChildNode[] children1;
+        @Children private final TestChildNode[] children2;
+
+        public TestRoot2Node(TestChildNode[] children1, TestChildNode[] children2) {
+            super(new TestChildNode[0]);
+            this.children1 = children1;
+            this.children2 = children2;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            int sum = 0;
+            for (int i = 0; i < children1.length; ++i) {
+                sum += children1[i].execute();
+            }
+            for (int i = 0; i < children2.length; ++i) {
+                sum += children2[i].execute();
+            }
+            return sum;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FinalFieldTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,108 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Using Final Fields in Node Classes</h3>
+ *
+ * <p>
+ * The usage of final fields in node classes is highly encouraged. It is beneficial for performance
+ * to declare every field that is not pointing to a child node as final. This gives the Truffle
+ * runtime an increased opportunity to optimize this node.
+ * </p>
+ *
+ * <p>
+ * If a node has a value which may change at run time, but will rarely do so, it is recommended to
+ * speculate on the field being final. This involves starting executing with a node where this field
+ * is final and only if this turns out to be no longer the case, the node is replaced with an
+ * alternative implementation of the operation (see {@link ReplaceTest}).
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.ReplaceTest}.
+ * </p>
+ */
+public class FinalFieldTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestRootNode rootNode = new TestRootNode(new TestChildNode[]{new TestChildNode(20), new TestChildNode(22)});
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+    }
+
+    private static class TestRootNode extends RootNode {
+
+        @Children private final TestChildNode[] children;
+
+        public TestRootNode(TestChildNode[] children) {
+            super(TestingLanguage.class, null, null);
+            this.children = children;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            int sum = 0;
+            for (int i = 0; i < children.length; ++i) {
+                sum += children[i].execute();
+            }
+            return sum;
+        }
+    }
+
+    private static class TestChildNode extends Node {
+
+        private final int value;
+
+        public TestChildNode(int value) {
+            super(null);
+            this.value = value;
+        }
+
+        public int execute() {
+            return value;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FrameDescriptorTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,117 @@
+/*
+ * 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;
+
+import com.oracle.truffle.api.frame.Frame;
+import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.FrameSlot;
+import com.oracle.truffle.api.frame.FrameSlotKind;
+import com.oracle.truffle.api.frame.FrameSlotTypeException;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import org.junit.Assert;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import org.junit.Test;
+
+public class FrameDescriptorTest {
+
+    private FrameSlot s1;
+    private FrameSlot s2;
+    private FrameSlot s3;
+
+    @Test
+    public void localsDefaultValue() throws Exception {
+        Object defaultValue = "default";
+        FrameDescriptor d = new FrameDescriptor(defaultValue);
+        s1 = d.addFrameSlot("v1");
+        s2 = d.addFrameSlot("v2");
+        s3 = d.addFrameSlot("v3");
+        VirtualFrame f = Truffle.getRuntime().createVirtualFrame(new Object[]{1, 2}, d);
+
+        assertFrame(f, d);
+        assertFrame(f.materialize(), d);
+    }
+
+    private void assertFrame(Frame f, FrameDescriptor d) throws FrameSlotTypeException {
+        assertEquals("Three slots", 3, d.getSize());
+        assertEquals("Three slots list", 3, d.getSlots().size());
+        assertEquals("1st slot", d.getSlots().get(0), s1);
+        assertEquals("2nd slot", d.getSlots().get(1), s2);
+        assertEquals("3rd slot", d.getSlots().get(2), s3);
+        assertEquals("default", f.getObject(s1));
+        assertEquals("default", f.getObject(s2));
+        f.setInt(s3, (int) f.getArguments()[0]);
+        assertEquals(1, f.getInt(s3));
+    }
+
+    @Test
+    public void nullDefaultValue() {
+        Assert.assertNull(new FrameDescriptor().getDefaultValue());
+    }
+
+    @Test
+    public void copy() throws Exception {
+        Object defaultValue = "default";
+        FrameDescriptor d = new FrameDescriptor(defaultValue);
+        s1 = d.addFrameSlot("v1", "i1", FrameSlotKind.Boolean);
+        s2 = d.addFrameSlot("v2", "i2", FrameSlotKind.Float);
+
+        assertEquals(2, d.getSize());
+        assertEquals(d.getSlots().get(1).getInfo(), "i2");
+        assertEquals(d.getSlots().get(1).getKind(), FrameSlotKind.Float);
+        assertEquals(d.getSlots().get(1).getIndex(), 1);
+
+        FrameDescriptor copy = d.copy();
+
+        assertEquals(copy.getSlots().get(1).getIndex(), 1);
+
+        assertNull("Info isn't copied!", copy.getSlots().get(1).getInfo());
+        assertEquals("Kind isn't copied!", copy.getSlots().get(1).getKind(), FrameSlotKind.Illegal);
+    }
+
+    @Test
+    public void shallowCopy() {
+        Object defaultValue = "default";
+        FrameDescriptor d = new FrameDescriptor(defaultValue);
+        s1 = d.addFrameSlot("v1", "i1", FrameSlotKind.Boolean);
+        s2 = d.addFrameSlot("v2", "i2", FrameSlotKind.Float);
+
+        assertEquals(2, d.getSize());
+        final FrameSlot first = d.getSlots().get(1);
+        assertEquals(first.getInfo(), "i2");
+        assertEquals(first.getKind(), FrameSlotKind.Float);
+        assertEquals(first.getIndex(), 1);
+
+        FrameDescriptor copy = d.shallowCopy();
+
+        assertEquals(2, copy.getSize());
+        final FrameSlot firstCopy = copy.getSlots().get(1);
+        assertEquals("Info is copied", firstCopy.getInfo(), "i2");
+        assertEquals("Kind is copied", firstCopy.getKind(), FrameSlotKind.Float);
+        assertEquals(firstCopy.getIndex(), 1);
+
+        firstCopy.setKind(FrameSlotKind.Int);
+        assertEquals("Kind is changed", firstCopy.getKind(), FrameSlotKind.Int);
+        assertEquals("Kind is changed in original too!", first.getKind(), FrameSlotKind.Int);
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FrameSlotTypeSpecializationTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,195 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.FrameSlot;
+import com.oracle.truffle.api.frame.FrameSlotKind;
+import com.oracle.truffle.api.frame.FrameSlotTypeException;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Specializing Frame Slot Types</h3>
+ *
+ * <p>
+ * Dynamically typed languages can speculate on the type of a frame slot and only fall back at run
+ * time to a more generic type if necessary. The new type of a frame slot can be set using the
+ * {@link FrameSlot#setKind(FrameSlotKind)} method.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at
+ * {@link com.oracle.truffle.api.ReturnTypeSpecializationTest}.
+ * </p>
+ */
+public class FrameSlotTypeSpecializationTest {
+
+    @Before
+    public void setInstrumentationTestMode() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void unsetInstrumentationTestMode() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        FrameDescriptor frameDescriptor = new FrameDescriptor();
+        FrameSlot slot = frameDescriptor.addFrameSlot("localVar", FrameSlotKind.Int);
+        TestRootNode rootNode = new TestRootNode(frameDescriptor, new IntAssignLocal(slot, new StringTestChildNode()), new IntReadLocal(slot));
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Assert.assertEquals(FrameSlotKind.Int, slot.getKind());
+        Object result = target.call();
+        Assert.assertEquals("42", result);
+        Assert.assertEquals(FrameSlotKind.Object, slot.getKind());
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Child TestChildNode left;
+        @Child TestChildNode right;
+
+        public TestRootNode(FrameDescriptor descriptor, TestChildNode left, TestChildNode right) {
+            super(TestingLanguage.class, null, descriptor);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            left.execute(frame);
+            return right.execute(frame);
+        }
+    }
+
+    abstract class TestChildNode extends Node {
+
+        protected TestChildNode() {
+            super(null);
+        }
+
+        abstract Object execute(VirtualFrame frame);
+    }
+
+    abstract class FrameSlotNode extends TestChildNode {
+
+        protected final FrameSlot slot;
+
+        public FrameSlotNode(FrameSlot slot) {
+            this.slot = slot;
+        }
+    }
+
+    class StringTestChildNode extends TestChildNode {
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            return "42";
+        }
+
+    }
+
+    class IntAssignLocal extends FrameSlotNode {
+
+        @Child private TestChildNode value;
+
+        IntAssignLocal(FrameSlot slot, TestChildNode value) {
+            super(slot);
+            this.value = value;
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            Object o = value.execute(frame);
+            if (o instanceof Integer) {
+                frame.setInt(slot, (Integer) o);
+            } else {
+                slot.setKind(FrameSlotKind.Object);
+                frame.setObject(slot, o);
+                this.replace(new ObjectAssignLocal(slot, value));
+            }
+            return null;
+        }
+    }
+
+    class ObjectAssignLocal extends FrameSlotNode {
+
+        @Child private TestChildNode value;
+
+        ObjectAssignLocal(FrameSlot slot, TestChildNode value) {
+            super(slot);
+            this.value = value;
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            Object o = value.execute(frame);
+            slot.setKind(FrameSlotKind.Object);
+            frame.setObject(slot, o);
+            return null;
+        }
+    }
+
+    class IntReadLocal extends FrameSlotNode {
+
+        IntReadLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            try {
+                return frame.getInt(slot);
+            } catch (FrameSlotTypeException e) {
+                return this.replace(new ObjectReadLocal(slot)).execute(frame);
+            }
+        }
+    }
+
+    class ObjectReadLocal extends FrameSlotNode {
+
+        ObjectReadLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            try {
+                return frame.getObject(slot);
+            } catch (FrameSlotTypeException e) {
+                throw new IllegalStateException(e);
+            }
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FrameTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,198 @@
+/*
+ * 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;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.Frame;
+import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.FrameInstance;
+import com.oracle.truffle.api.frame.FrameSlot;
+import com.oracle.truffle.api.frame.FrameSlotKind;
+import com.oracle.truffle.api.frame.FrameSlotTypeException;
+import com.oracle.truffle.api.frame.MaterializedFrame;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Storing Values in Frame Slots</h3>
+ *
+ * <p>
+ * The frame is the preferred data structure for passing values between nodes. It can in particular
+ * be used for storing the values of local variables of the guest language. The
+ * {@link FrameDescriptor} represents the current structure of the frame. The method
+ * {@link FrameDescriptor#addFrameSlot(Object, FrameSlotKind)} can be used to create predefined
+ * frame slots. The setter and getter methods in the {@link Frame} class can be used to access the
+ * current value of a particular frame slot. Values can be removed from a frame via the
+ * {@link FrameDescriptor#removeFrameSlot(Object)} method.
+ * </p>
+ *
+ * <p>
+ * There are five primitive types for slots available: {@link java.lang.Boolean},
+ * {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Float}, and
+ * {@link java.lang.Double} . It is encouraged to use those types whenever possible. Dynamically
+ * typed languages can speculate on the type of a value fitting into a primitive (see
+ * {@link FrameSlotTypeSpecializationTest}). When a frame slot is of one of those particular
+ * primitive types, its value may only be accessed with the respectively typed getter method (
+ * {@link Frame#getBoolean}, {@link Frame#getInt}, {@link Frame#getLong}, {@link Frame#getFloat}, or
+ * {@link Frame#getDouble}) or setter method ({@link Frame#setBoolean}, {@link Frame#setInt},
+ * {@link Frame#setLong}, {@link Frame#setFloat}, or {@link Frame#setDouble}) in the {@link Frame}
+ * class.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at
+ * {@link com.oracle.truffle.api.FrameSlotTypeSpecializationTest}.
+ * </p>
+ */
+public class FrameTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() throws SecurityException, IllegalArgumentException {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        FrameDescriptor frameDescriptor = new FrameDescriptor();
+        String varName = "localVar";
+        FrameSlot slot = frameDescriptor.addFrameSlot(varName, FrameSlotKind.Int);
+        TestRootNode rootNode = new TestRootNode(frameDescriptor, new AssignLocal(slot), new ReadLocal(slot));
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+        frameDescriptor.removeFrameSlot(varName);
+        boolean slotMissing = false;
+        try {
+            result = target.call();
+        } catch (IllegalArgumentException iae) {
+            slotMissing = true;
+        }
+        Assert.assertTrue(slotMissing);
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Child TestChildNode left;
+        @Child TestChildNode right;
+
+        public TestRootNode(FrameDescriptor descriptor, TestChildNode left, TestChildNode right) {
+            super(TestingLanguage.class, null, descriptor);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return left.execute(frame) + right.execute(frame);
+        }
+    }
+
+    abstract class TestChildNode extends Node {
+
+        public TestChildNode() {
+            super(null);
+        }
+
+        abstract int execute(VirtualFrame frame);
+    }
+
+    abstract class FrameSlotNode extends TestChildNode {
+
+        protected final FrameSlot slot;
+
+        public FrameSlotNode(FrameSlot slot) {
+            this.slot = slot;
+        }
+    }
+
+    class AssignLocal extends FrameSlotNode {
+
+        AssignLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            frame.setInt(slot, 42);
+            return 0;
+        }
+    }
+
+    class ReadLocal extends FrameSlotNode {
+
+        ReadLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            try {
+                return frame.getInt(slot);
+            } catch (FrameSlotTypeException e) {
+                throw new IllegalStateException(e);
+            }
+        }
+    }
+
+    @Test
+    public void framesCanBeMaterialized() {
+        final TruffleRuntime runtime = Truffle.getRuntime();
+
+        class FrameRootNode extends RootNode {
+
+            public FrameRootNode() {
+                super(TestingLanguage.class, null, null);
+            }
+
+            @Override
+            public Object execute(VirtualFrame frame) {
+                FrameInstance frameInstance = runtime.getCurrentFrame();
+                Frame readWrite = frameInstance.getFrame(FrameInstance.FrameAccess.READ_WRITE, true);
+                Frame materialized = frameInstance.getFrame(FrameInstance.FrameAccess.MATERIALIZE, true);
+
+                assertTrue("Really materialized: " + materialized, materialized instanceof MaterializedFrame);
+                assertEquals("It's my frame", frame, readWrite);
+                return this;
+            }
+        }
+
+        FrameRootNode frn = new FrameRootNode();
+        Object ret = Truffle.getRuntime().createCallTarget(frn).call();
+        assertEquals("Returns itself", frn, ret);
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/InterfaceChildFieldTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2014, 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;
+
+import java.util.Iterator;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.NodeInterface;
+import com.oracle.truffle.api.nodes.NodeUtil;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * Test child fields declared with interface types instead of {@link Node} subclasses.
+ */
+public class InterfaceChildFieldTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void testChild() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildInterface leftChild = new TestLeafNode();
+        TestChildInterface rightChild = new TestLeafNode();
+        TestChildNode parent = new TestChildNode(leftChild, rightChild);
+        TestRootNode rootNode = new TestRootNode(parent);
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Iterator<Node> iterator = parent.getChildren().iterator();
+        Assert.assertEquals(leftChild, iterator.next());
+        Assert.assertEquals(rightChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+
+        Assert.assertEquals(4, NodeUtil.countNodes(rootNode));
+        Assert.assertEquals(4, NodeUtil.countNodes(NodeUtil.cloneNode(rootNode)));
+    }
+
+    @Test
+    public void testChildren() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestChildInterface[] children = new TestChildInterface[5];
+        for (int i = 0; i < children.length; i++) {
+            children[i] = new TestLeafNode();
+        }
+        TestChildrenNode parent = new TestChildrenNode(children);
+        TestRootNode rootNode = new TestRootNode(parent);
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Iterator<Node> iterator = parent.getChildren().iterator();
+        for (int i = 0; i < children.length; i++) {
+            Assert.assertEquals(children[i], iterator.next());
+        }
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        Assert.assertEquals(105, result);
+
+        Assert.assertEquals(2 + children.length, NodeUtil.countNodes(rootNode));
+        Assert.assertEquals(2 + children.length, NodeUtil.countNodes(NodeUtil.cloneNode(rootNode)));
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Child private TestChildInterface child;
+
+        public TestRootNode(TestChildInterface child) {
+            super(TestingLanguage.class, null, null);
+            this.child = child;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return child.executeIntf();
+        }
+    }
+
+    interface TestChildInterface extends NodeInterface {
+        int executeIntf();
+    }
+
+    class TestLeafNode extends Node implements TestChildInterface {
+        public TestLeafNode() {
+            super(null);
+        }
+
+        public int executeIntf() {
+            return this.replace(new TestLeaf2Node()).executeIntf();
+        }
+    }
+
+    class TestLeaf2Node extends Node implements TestChildInterface {
+        public TestLeaf2Node() {
+            super(null);
+        }
+
+        public int executeIntf() {
+            return 21;
+        }
+    }
+
+    class TestChildNode extends Node implements TestChildInterface {
+
+        @Child private TestChildInterface left;
+        @Child private TestChildInterface right;
+
+        public TestChildNode(TestChildInterface left, TestChildInterface right) {
+            super(null);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public int executeIntf() {
+            return left.executeIntf() + right.executeIntf();
+        }
+    }
+
+    class TestChildrenNode extends Node implements TestChildInterface {
+
+        @Children private final TestChildInterface[] children;
+
+        public TestChildrenNode(TestChildInterface[] children) {
+            super(null);
+            this.children = children;
+        }
+
+        @Override
+        public int executeIntf() {
+            int sum = 0;
+            for (int i = 0; i < children.length; ++i) {
+                sum += children[i].executeIntf();
+            }
+            return sum;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ReplaceTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,153 @@
+/*
+ * 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;
+
+import static org.junit.Assert.assertEquals;
+
+import java.util.Iterator;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Replacing Nodes at Run Time</h3>
+ *
+ * <p>
+ * The structure of the Truffle tree can be changed at run time by replacing nodes using the
+ * {@link Node#replace(Node)} method. This method will automatically change the child pointer in the
+ * parent of the node and replace it with a pointer to the new node.
+ * </p>
+ *
+ * <p>
+ * Replacing nodes is a costly operation, so it should not happen too often. The convention is that
+ * the implementation of the Truffle nodes should ensure that there are maximal a small (and
+ * constant) number of node replacements per Truffle node.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.CallTest}.
+ * </p>
+ */
+public class ReplaceTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        UnresolvedNode leftChild = new UnresolvedNode("20");
+        UnresolvedNode rightChild = new UnresolvedNode("22");
+        TestRootNode rootNode = new TestRootNode(new ValueNode[]{leftChild, rightChild});
+        CallTarget target = runtime.createCallTarget(rootNode);
+        assertEquals(rootNode, leftChild.getParent());
+        assertEquals(rootNode, rightChild.getParent());
+        Iterator<Node> iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(leftChild, iterator.next());
+        Assert.assertEquals(rightChild, iterator.next());
+        Assert.assertFalse(iterator.hasNext());
+        Object result = target.call();
+        assertEquals(42, result);
+        assertEquals(42, target.call());
+        iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(ResolvedNode.class, iterator.next().getClass());
+        Assert.assertEquals(ResolvedNode.class, iterator.next().getClass());
+        Assert.assertFalse(iterator.hasNext());
+        iterator = rootNode.getChildren().iterator();
+        Assert.assertEquals(rootNode, iterator.next().getParent());
+        Assert.assertEquals(rootNode, iterator.next().getParent());
+        Assert.assertFalse(iterator.hasNext());
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Children private final ValueNode[] children;
+
+        public TestRootNode(ValueNode[] children) {
+            super(TestingLanguage.class, null, null);
+            this.children = children;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            int sum = 0;
+            for (int i = 0; i < children.length; ++i) {
+                sum += children[i].execute();
+            }
+            return sum;
+        }
+    }
+
+    abstract class ValueNode extends Node {
+
+        public ValueNode() {
+            super(null);
+        }
+
+        abstract int execute();
+    }
+
+    class UnresolvedNode extends ValueNode {
+
+        private final String value;
+
+        public UnresolvedNode(String value) {
+            this.value = value;
+        }
+
+        @Override
+        int execute() {
+            int intValue = Integer.parseInt(value);
+            ResolvedNode newNode = this.replace(new ResolvedNode(intValue));
+            return newNode.execute();
+        }
+    }
+
+    class ResolvedNode extends ValueNode {
+
+        private final int value;
+
+        ResolvedNode(int value) {
+            this.value = value;
+        }
+
+        @Override
+        int execute() {
+            return value;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ReturnTypeSpecializationTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,212 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.FrameSlot;
+import com.oracle.truffle.api.frame.FrameSlotKind;
+import com.oracle.truffle.api.frame.FrameSlotTypeException;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.nodes.UnexpectedResultException;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Specializing Return Types</h3>
+ *
+ * <p>
+ * In order to avoid boxing and/or type casts on the return value of a node, the return value the
+ * method for executing a node can have a specific type and need not be of type
+ * {@link java.lang.Object}. For dynamically typed languages, this return type is something that
+ * should be speculated on. When the speculation fails and the child node cannot return the
+ * appropriate type of value, it can use an {@link UnexpectedResultException} to still pass the
+ * result to the caller. In such a case, the caller must rewrite itself to a more general version in
+ * order to avoid future failures of this kind.
+ * </p>
+ */
+public class ReturnTypeSpecializationTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        FrameDescriptor frameDescriptor = new FrameDescriptor();
+        FrameSlot slot = frameDescriptor.addFrameSlot("localVar", FrameSlotKind.Int);
+        TestRootNode rootNode = new TestRootNode(frameDescriptor, new IntAssignLocal(slot, new StringTestChildNode()), new IntReadLocal(slot));
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Assert.assertEquals(FrameSlotKind.Int, slot.getKind());
+        Object result = target.call();
+        Assert.assertEquals("42", result);
+        Assert.assertEquals(FrameSlotKind.Object, slot.getKind());
+    }
+
+    class TestRootNode extends RootNode {
+
+        @Child TestChildNode left;
+        @Child TestChildNode right;
+
+        public TestRootNode(FrameDescriptor descriptor, TestChildNode left, TestChildNode right) {
+            super(TestingLanguage.class, null, descriptor);
+            this.left = left;
+            this.right = right;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            left.execute(frame);
+            return right.execute(frame);
+        }
+    }
+
+    abstract class TestChildNode extends Node {
+
+        public TestChildNode() {
+            super(null);
+        }
+
+        abstract Object execute(VirtualFrame frame);
+
+        int executeInt(VirtualFrame frame) throws UnexpectedResultException {
+            Object result = execute(frame);
+            if (result instanceof Integer) {
+                return (Integer) result;
+            }
+            throw new UnexpectedResultException(result);
+        }
+    }
+
+    abstract class FrameSlotNode extends TestChildNode {
+
+        protected final FrameSlot slot;
+
+        public FrameSlotNode(FrameSlot slot) {
+            this.slot = slot;
+        }
+    }
+
+    class StringTestChildNode extends TestChildNode {
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            return "42";
+        }
+
+    }
+
+    class IntAssignLocal extends FrameSlotNode {
+
+        @Child private TestChildNode value;
+
+        IntAssignLocal(FrameSlot slot, TestChildNode value) {
+            super(slot);
+            this.value = value;
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            try {
+                int result = value.executeInt(frame);
+                frame.setInt(slot, result);
+            } catch (UnexpectedResultException e) {
+                slot.setKind(FrameSlotKind.Object);
+                frame.setObject(slot, e.getResult());
+                replace(new ObjectAssignLocal(slot, value));
+            }
+            return null;
+        }
+    }
+
+    class ObjectAssignLocal extends FrameSlotNode {
+
+        @Child private TestChildNode value;
+
+        ObjectAssignLocal(FrameSlot slot, TestChildNode value) {
+            super(slot);
+            this.value = value;
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            Object o = value.execute(frame);
+            slot.setKind(FrameSlotKind.Object);
+            frame.setObject(slot, o);
+            return null;
+        }
+    }
+
+    class IntReadLocal extends FrameSlotNode {
+
+        IntReadLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            try {
+                return frame.getInt(slot);
+            } catch (FrameSlotTypeException e) {
+                return replace(new ObjectReadLocal(slot)).execute(frame);
+            }
+        }
+
+        @Override
+        int executeInt(VirtualFrame frame) throws UnexpectedResultException {
+            try {
+                return frame.getInt(slot);
+            } catch (FrameSlotTypeException e) {
+                return replace(new ObjectReadLocal(slot)).executeInt(frame);
+            }
+        }
+    }
+
+    class ObjectReadLocal extends FrameSlotNode {
+
+        ObjectReadLocal(FrameSlot slot) {
+            super(slot);
+        }
+
+        @Override
+        Object execute(VirtualFrame frame) {
+            try {
+                return frame.getObject(slot);
+            } catch (FrameSlotTypeException e) {
+                throw new IllegalStateException(e);
+            }
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/RootNodeTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,83 @@
+/*
+ * 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;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Creating a Root Node</h3>
+ *
+ * <p>
+ * A Truffle root node is the entry point into a Truffle tree that represents a guest language
+ * method. It contains a {@link RootNode#execute(VirtualFrame)} method that can return a
+ * {@link java.lang.Object} value as the result of the guest language method invocation. This method
+ * must however never be called directly. Instead, the Truffle runtime must be used to create a
+ * {@link CallTarget} object from a root node using the
+ * {@link TruffleRuntime#createCallTarget(RootNode)} method. This call target object can then be
+ * executed using the {@link CallTarget#call(Object...)} method or one of its overloads.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.ChildNodeTest}.
+ * </p>
+ */
+public class RootNodeTest {
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    @Test
+    public void test() {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestRootNode rootNode = new TestRootNode();
+        CallTarget target = runtime.createCallTarget(rootNode);
+        Object result = target.call();
+        Assert.assertEquals(42, result);
+    }
+
+    class TestRootNode extends RootNode {
+
+        public TestRootNode() {
+            super(TestingLanguage.class, null, null);
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return 42;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/TestingLanguage.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,84 @@
+/*
+ * 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;
+
+import java.io.IOException;
+
+import com.oracle.truffle.api.frame.MaterializedFrame;
+import com.oracle.truffle.api.instrument.Visualizer;
+import com.oracle.truffle.api.instrument.WrapperNode;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.source.Source;
+
+public final class TestingLanguage extends TruffleLanguage<Object> {
+    public static final TestingLanguage INSTANCE = new TestingLanguage();
+
+    private TestingLanguage() {
+    }
+
+    @Override
+    protected CallTarget parse(Source code, Node context, String... argumentNames) throws IOException {
+        throw new IOException();
+    }
+
+    @Override
+    protected Object findExportedSymbol(Object context, String globalName, boolean onlyExplicit) {
+        return null;
+    }
+
+    @Override
+    protected Object getLanguageGlobal(Object context) {
+        return null;
+    }
+
+    @Override
+    protected boolean isObjectOfLanguage(Object object) {
+        return false;
+    }
+
+    @Override
+    protected Visualizer getVisualizer() {
+        return null;
+    }
+
+    @Override
+    protected boolean isInstrumentable(Node node) {
+        return false;
+    }
+
+    @Override
+    protected WrapperNode createWrapperNode(Node node) {
+        return null;
+    }
+
+    @Override
+    protected Object evalInContext(Source source, Node node, MaterializedFrame mFrame) throws IOException {
+        return null;
+    }
+
+    @Override
+    protected Object createContext(Env env) {
+        return null;
+    }
+
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/ThreadSafetyTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,194 @@
+/*
+ * Copyright (c) 2014, 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;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import java.util.Random;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import org.junit.Ignore;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.DirectCallNode;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.NodeUtil;
+import com.oracle.truffle.api.nodes.RootNode;
+
+/**
+ * Test node rewriting in a tree shared across multiple threads (run with -ea).
+ */
+public class ThreadSafetyTest {
+
+    @Test
+    @Ignore("sporadic failures with \"expected:<1000000> but was:<999999>\"")
+    public void test() throws InterruptedException {
+        TruffleRuntime runtime = Truffle.getRuntime();
+        TestRootNode rootNode1 = new TestRootNode(new RewritingNode(new RewritingNode(new RewritingNode(new RewritingNode(new RewritingNode(new ConstNode(42)))))));
+        final CallTarget target1 = runtime.createCallTarget(rootNode1);
+        NodeUtil.verify(rootNode1);
+
+        RecursiveCallNode callNode = new RecursiveCallNode(new ConstNode(42));
+        TestRootNode rootNode2 = new TestRootNode(new RewritingNode(new RewritingNode(new RewritingNode(new RewritingNode(new RewritingNode(callNode))))));
+        final CallTarget target2 = runtime.createCallTarget(rootNode2);
+        callNode.setCallNode(runtime.createDirectCallNode(target2));
+        NodeUtil.verify(rootNode2);
+
+        testTarget(target1, 47, 1_000_000);
+        testTarget(target2, 72, 1_000_000);
+    }
+
+    private static void testTarget(final CallTarget target, final int expectedResult, final int numberOfIterations) throws InterruptedException {
+        ExecutorService executorService = Executors.newFixedThreadPool(20);
+        final AtomicInteger ai = new AtomicInteger();
+        for (int i = 0; i < numberOfIterations; i++) {
+            executorService.submit(new Runnable() {
+                public void run() {
+                    try {
+                        Object result = target.call(new Object[]{5});
+                        assertEquals(expectedResult, result);
+                        ai.incrementAndGet();
+                    } catch (Throwable t) {
+                        t.printStackTrace(System.out);
+                    }
+                }
+            });
+        }
+        executorService.shutdown();
+        executorService.awaitTermination(90, TimeUnit.SECONDS);
+        assertTrue("test did not terminate", executorService.isTerminated());
+        assertEquals(numberOfIterations, ai.get());
+    }
+
+    static class TestRootNode extends RootNode {
+
+        @Child private ValueNode child;
+
+        public TestRootNode(ValueNode child) {
+            super(TestingLanguage.class, null, null);
+            this.child = child;
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return child.execute(frame);
+        }
+    }
+
+    abstract static class ValueNode extends Node {
+
+        public ValueNode() {
+            super(null);
+        }
+
+        abstract int execute(VirtualFrame frame);
+    }
+
+    static class RewritingNode extends ValueNode {
+
+        @Child private ValueNode child;
+        private final Random random;
+
+        public RewritingNode(ValueNode child) {
+            this(child, new Random());
+        }
+
+        public RewritingNode(ValueNode child, Random random) {
+            this.child = child;
+            this.random = random;
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            boolean replace = random.nextBoolean();
+            if (replace) {
+                ValueNode newNode = this.replace(new OtherRewritingNode(child, random));
+                return newNode.execute(frame);
+            }
+            return 1 + child.execute(frame);
+        }
+    }
+
+    static class OtherRewritingNode extends ValueNode {
+
+        @Child private ValueNode child;
+        private final Random random;
+
+        public OtherRewritingNode(ValueNode child, Random random) {
+            this.child = child;
+            this.random = random;
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            boolean replace = random.nextBoolean();
+            if (replace) {
+                ValueNode newNode = this.replace(new RewritingNode(child, random));
+                return newNode.execute(frame);
+            }
+            return 1 + child.execute(frame);
+        }
+    }
+
+    static class ConstNode extends ValueNode {
+
+        private final int value;
+
+        ConstNode(int value) {
+            this.value = value;
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            return value;
+        }
+    }
+
+    static class RecursiveCallNode extends ValueNode {
+        @Child DirectCallNode callNode;
+        @Child private ValueNode valueNode;
+
+        RecursiveCallNode(ValueNode value) {
+            this.valueNode = value;
+        }
+
+        @Override
+        int execute(VirtualFrame frame) {
+            int arg = (Integer) frame.getArguments()[0];
+            if (arg > 0) {
+                return (int) callNode.call(frame, new Object[]{(arg - 1)});
+            } else {
+                return valueNode.execute(frame);
+            }
+        }
+
+        void setCallNode(DirectCallNode callNode) {
+            this.callNode = insert(callNode);
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/TruffleRuntimeTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,177 @@
+/*
+ * Copyright (c) 2012, 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;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.NodeUtil;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.source.Source;
+import com.oracle.truffle.api.source.SourceSection;
+import com.oracle.truffle.api.utilities.InstrumentationTestMode;
+
+/**
+ * <h3>Accessing the Truffle Runtime</h3>
+ *
+ * <p>
+ * The Truffle runtime can be accessed at any point in time globally using the static method
+ * {@link Truffle#getRuntime()}. This method is guaranteed to return a non-null Truffle runtime
+ * object with an identifying name. A Java Virtual Machine implementation can chose to replace the
+ * default implementation of the {@link TruffleRuntime} interface with its own implementation for
+ * providing improved performance.
+ * </p>
+ *
+ * <p>
+ * The next part of the Truffle API introduction is at {@link com.oracle.truffle.api.RootNodeTest}.
+ * </p>
+ */
+public class TruffleRuntimeTest {
+
+    private TruffleRuntime runtime;
+
+    @Before
+    public void before() {
+        InstrumentationTestMode.set(true);
+        this.runtime = Truffle.getRuntime();
+    }
+
+    @After
+    public void after() {
+        InstrumentationTestMode.set(false);
+    }
+
+    private static RootNode createTestRootNode(SourceSection sourceSection) {
+        return new RootNode(TestingLanguage.class, sourceSection, null) {
+            @Override
+            public Object execute(VirtualFrame frame) {
+                return 42;
+            }
+        };
+    }
+
+    // @Test
+    public void verifyTheRealRuntimeIsUsedOnRealGraal() {
+        TruffleRuntime r = Truffle.getRuntime();
+        final String name = r.getClass().getName();
+        if (name.endsWith("DefaultTruffleRuntime")) {
+            fail("Wrong name " + name + " with following System.getProperties:\n" + System.getProperties().toString());
+        }
+    }
+
+    @Test
+    public void test() {
+        assertNotNull(runtime);
+        assertNotNull(runtime.getName());
+    }
+
+    @Test
+    public void testCreateCallTarget() {
+        RootNode rootNode = createTestRootNode(null);
+        RootCallTarget target = runtime.createCallTarget(rootNode);
+        assertNotNull(target);
+        assertEquals(target.call(), 42);
+        assertSame(rootNode, target.getRootNode());
+    }
+
+    @Test
+    public void testGetCallTargets1() {
+        RootNode rootNode = createTestRootNode(null);
+        RootCallTarget target = runtime.createCallTarget(rootNode);
+        assertTrue(runtime.getCallTargets().contains(target));
+    }
+
+    @Test
+    public void testGetCallTargets2() {
+        RootNode rootNode = createTestRootNode(null);
+        RootCallTarget target1 = runtime.createCallTarget(rootNode);
+        RootCallTarget target2 = runtime.createCallTarget(rootNode);
+        assertTrue(runtime.getCallTargets().contains(target1));
+        assertTrue(runtime.getCallTargets().contains(target2));
+    }
+
+    /*
+     * This test case documents the use case for profilers and debuggers where they need to access
+     * multiple call targets for the same source section. This case may happen when the optimization
+     * system decides to duplicate call targets to achieve better performance.
+     */
+    @Test
+    public void testGetCallTargets3() {
+        Source source1 = Source.fromText("a\nb\n", "");
+        SourceSection sourceSection1 = source1.createSection("foo", 1);
+        SourceSection sourceSection2 = source1.createSection("bar", 2);
+
+        RootNode rootNode1 = createTestRootNode(sourceSection1);
+        RootNode rootNode2 = createTestRootNode(sourceSection2);
+        RootNode rootNode2Copy = NodeUtil.cloneNode(rootNode2);
+
+        assertSame(rootNode2.getSourceSection(), rootNode2Copy.getSourceSection());
+
+        RootCallTarget target1 = runtime.createCallTarget(rootNode1);
+        RootCallTarget target2 = runtime.createCallTarget(rootNode2);
+        RootCallTarget target2Copy = runtime.createCallTarget(rootNode2Copy);
+
+        Map<SourceSection, List<RootCallTarget>> groupedTargets = groupUniqueCallTargets();
+
+        List<RootCallTarget> targets1 = groupedTargets.get(sourceSection1);
+        assertEquals(1, targets1.size());
+        assertEquals(target1, targets1.get(0));
+
+        List<RootCallTarget> targets2 = groupedTargets.get(sourceSection2);
+        assertEquals(2, targets2.size());
+        // order of targets2 is not guaranteed
+        assertTrue(target2 == targets2.get(0) ^ target2Copy == targets2.get(0));
+        assertTrue(target2 == targets2.get(1) ^ target2Copy == targets2.get(1));
+    }
+
+    private static Map<SourceSection, List<RootCallTarget>> groupUniqueCallTargets() {
+        Map<SourceSection, List<RootCallTarget>> groupedTargets = new HashMap<>();
+        for (RootCallTarget target : Truffle.getRuntime().getCallTargets()) {
+            SourceSection section = target.getRootNode().getSourceSection();
+            if (section == null) {
+                // can not identify root node to a unique call target. Print warning?
+                continue;
+            }
+            List<RootCallTarget> targets = groupedTargets.get(section);
+            if (targets == null) {
+                targets = new ArrayList<>();
+                groupedTargets.put(section, targets);
+            }
+            targets.add(target);
+        }
+        return groupedTargets;
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/impl/AccessorTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2015, 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.impl;
+
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+
+import java.lang.reflect.Field;
+import java.util.concurrent.Executors;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import com.oracle.truffle.api.source.Source;
+import com.oracle.truffle.api.vm.ImplicitExplicitExportTest.ExportImportLanguage1;
+import static com.oracle.truffle.api.vm.ImplicitExplicitExportTest.L1;
+import com.oracle.truffle.api.vm.PolyglotEngine;
+
+public class AccessorTest {
+    public static Accessor API;
+
+    @BeforeClass
+    public static void initAccessors() throws Exception {
+        Field f = Accessor.class.getDeclaredField("API");
+        f.setAccessible(true);
+        API = (Accessor) f.get(null);
+    }
+
+    @Test
+    public void canGetAccessToOwnLanguageInstance() throws Exception {
+        PolyglotEngine vm = PolyglotEngine.newBuilder().executor(Executors.newSingleThreadExecutor()).build();
+        PolyglotEngine.Language language = vm.getLanguages().get(L1);
+        assertNotNull("L1 language is defined", language);
+
+        Source s = Source.fromText("return nothing", "nothing");
+        Object ret = language.eval(s).get();
+        assertNull("nothing is returned", ret);
+
+        ExportImportLanguage1 afterInitialization = Accessor.findLanguageByClass(vm, ExportImportLanguage1.class);
+        assertNotNull("Language found", afterInitialization);
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/instrument/EvalInstrumentTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,134 @@
+/*
+ * 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.instrument;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.fail;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.instrument.InstrumentationTestingLanguage.InstrumentTestTag;
+import com.oracle.truffle.api.instrument.impl.DefaultProbeListener;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.source.Source;
+import com.oracle.truffle.api.vm.PolyglotEngine;
+
+/**
+ * Tests the kind of instrumentation where a client can provide guest language code to be
+ * <em>spliced</em> directly into the AST.
+ */
+public class EvalInstrumentTest {
+
+    PolyglotEngine vm;
+    Instrumenter instrumenter;
+
+    @Before
+    public void before() {
+        // TODO (mlvdv) eventually abstract this
+        try {
+            vm = PolyglotEngine.newBuilder().build();
+            final Field field = PolyglotEngine.class.getDeclaredField("instrumenter");
+            field.setAccessible(true);
+            instrumenter = (Instrumenter) field.get(vm);
+            final java.lang.reflect.Field testVMField = Instrumenter.class.getDeclaredField("testVM");
+            testVMField.setAccessible(true);
+            testVMField.set(instrumenter, vm);
+        } catch (NoSuchFieldException | SecurityException | IllegalArgumentException | IllegalAccessException ex) {
+            fail("Reflective access to Instrumenter for testing");
+        }
+    }
+
+    @After
+    public void after() {
+        vm.dispose();
+        vm = null;
+        instrumenter = null;
+    }
+
+    @Test
+    public void testEvalInstrumentListener() throws IOException {
+
+        instrumenter.registerASTProber(new InstrumentationTestingLanguage.TestASTProber());
+        final Source source13 = InstrumentationTestingLanguage.createAdditionSource13("testEvalInstrumentListener");
+
+        final Probe[] addNodeProbe = new Probe[1];
+        instrumenter.addProbeListener(new DefaultProbeListener() {
+
+            @Override
+            public void probeTaggedAs(Probe probe, SyntaxTag tag, Object tagValue) {
+                if (tag == InstrumentTestTag.ADD_TAG) {
+                    addNodeProbe[0] = probe;
+                }
+            }
+        });
+        assertEquals(vm.eval(source13).get(), 13);
+        assertNotNull("Add node should be probed", addNodeProbe[0]);
+
+        final Source source42 = InstrumentationTestingLanguage.createConstantSource42("testEvalInstrumentListener");
+        final int[] evalResult = {0};
+        final int[] evalCount = {0};
+        final Instrument instrument = instrumenter.attach(addNodeProbe[0], source42, new EvalInstrumentListener() {
+
+            public void onExecution(Node node, VirtualFrame vFrame, Object result) {
+                evalCount[0] = evalCount[0] + 1;
+                if (result instanceof Integer) {
+                    evalResult[0] = (Integer) result;
+                }
+            }
+
+            public void onFailure(Node node, VirtualFrame vFrame, Exception ex) {
+                fail("Eval test evaluates without exception");
+
+            }
+        }, "test EvalInstrument", null);
+
+        assertEquals(vm.eval(source13).get(), 13);
+        assertEquals(evalCount[0], 1);
+        assertEquals(evalResult[0], 42);
+
+        // Second execution; same result
+        assertEquals(vm.eval(source13).get(), 13);
+        assertEquals(evalCount[0], 2);
+        assertEquals(evalResult[0], 42);
+
+        // Add new eval instrument with no listener, no effect on third execution
+        instrumenter.attach(addNodeProbe[0], source42, null, "", null);
+        assertEquals(vm.eval(source13).get(), 13);
+        assertEquals(evalCount[0], 3);
+        assertEquals(evalResult[0], 42);
+
+        // Remove original instrument; no further effect from fourth execution
+        instrument.dispose();
+        evalResult[0] = 0;
+        assertEquals(vm.eval(source13).get(), 13);
+        assertEquals(evalCount[0], 3);
+        assertEquals(evalResult[0], 0);
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/instrument/InstrumentationTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,377 @@
+/*
+ * Copyright (c) 2014, 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.instrument;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.fail;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+
+import org.junit.Test;
+
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestAdditionNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestLanguageNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestValueNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestingLanguage.InstrumentTestTag;
+import com.oracle.truffle.api.instrument.impl.DefaultProbeListener;
+import com.oracle.truffle.api.instrument.impl.DefaultSimpleInstrumentListener;
+import com.oracle.truffle.api.instrument.impl.DefaultStandardInstrumentListener;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.NodeVisitor;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.source.Source;
+import com.oracle.truffle.api.vm.PolyglotEngine;
+
+/**
+ * <h3>AST Instrumentation</h3>
+ *
+ * Instrumentation allows the insertion into Truffle ASTs language-specific instances of
+ * {@link WrapperNode} that propagate execution events through a {@link Probe} to any instances of
+ * {@link ProbeInstrument} that might be attached to the particular probe by tools.
+ */
+public class InstrumentationTest {
+
+    @Test
+    public void testProbing() throws NoSuchFieldException, SecurityException, IllegalArgumentException, IllegalAccessException, IOException {
+        final PolyglotEngine vm = PolyglotEngine.newBuilder().build();
+        final Field field = PolyglotEngine.class.getDeclaredField("instrumenter");
+        field.setAccessible(true);
+        final Instrumenter instrumenter = (Instrumenter) field.get(vm);
+        instrumenter.registerASTProber(new TestASTProber(instrumenter));
+        final Source source = InstrumentationTestingLanguage.createAdditionSource13("testProbing");
+
+        final Probe[] probes = new Probe[3];
+        instrumenter.addProbeListener(new DefaultProbeListener() {
+
+            @Override
+            public void probeTaggedAs(Probe probe, SyntaxTag tag, Object tagValue) {
+                if (tag == InstrumentTestTag.ADD_TAG) {
+                    assertEquals(probes[0], null);
+                    probes[0] = probe;
+                } else if (tag == InstrumentTestTag.VALUE_TAG) {
+                    if (probes[1] == null) {
+                        probes[1] = probe;
+                    } else if (probes[2] == null) {
+                        probes[2] = probe;
+                    } else {
+                        fail("Should only be three probes");
+                    }
+                }
+            }
+        });
+        assertEquals(vm.eval(source).get(), 13);
+        assertNotNull("Add node should be probed", probes[0]);
+        assertNotNull("Value nodes should be probed", probes[1]);
+        assertNotNull("Value nodes should be probed", probes[2]);
+        // Check instrumentation with the simplest kind of counters.
+        // They should all be removed when the check is finished.
+        checkCounters(probes[0], vm, source, new TestSimpleInstrumentCounter(instrumenter), new TestSimpleInstrumentCounter(instrumenter), new TestSimpleInstrumentCounter(instrumenter));
+
+        // Now try with the more complex flavor of listener
+        checkCounters(probes[0], vm, source, new TestStandardInstrumentCounter(instrumenter), new TestStandardInstrumentCounter(instrumenter), new TestStandardInstrumentCounter(instrumenter));
+
+    }
+
+    @Test
+    public void testTagging() throws NoSuchFieldException, SecurityException, IllegalArgumentException, IllegalAccessException, IOException {
+
+        final PolyglotEngine vm = PolyglotEngine.newBuilder().build();
+        final Field field = PolyglotEngine.class.getDeclaredField("instrumenter");
+        field.setAccessible(true);
+        final Instrumenter instrumenter = (Instrumenter) field.get(vm);
+        final Source source = InstrumentationTestingLanguage.createAdditionSource13("testTagging");
+
+        // Applies appropriate tags
+        final TestASTProber astProber = new TestASTProber(instrumenter);
+        instrumenter.registerASTProber(astProber);
+
+        // Listens for probes and tags being added
+        final TestProbeListener probeListener = new TestProbeListener();
+        instrumenter.addProbeListener(probeListener);
+
+        assertEquals(13, vm.eval(source).get());
+
+        // Check that the prober added probes to the tree
+        assertEquals(probeListener.probeCount, 3);
+        assertEquals(probeListener.tagCount, 3);
+
+        assertEquals(instrumenter.findProbesTaggedAs(InstrumentTestTag.ADD_TAG).size(), 1);
+        assertEquals(instrumenter.findProbesTaggedAs(InstrumentTestTag.VALUE_TAG).size(), 2);
+    }
+
+    private static void checkCounters(Probe probe, PolyglotEngine vm, Source source, TestCounter counterA, TestCounter counterB, TestCounter counterC) throws IOException {
+
+        // Attach a counting instrument to the probe
+        counterA.attach(probe);
+
+        // Attach a second counting instrument to the probe
+        counterB.attach(probe);
+
+        // Run it again and check that the two instruments are working
+        assertEquals(13, vm.eval(source).get());
+        assertEquals(counterA.enterCount(), 1);
+        assertEquals(counterA.leaveCount(), 1);
+        assertEquals(counterB.enterCount(), 1);
+        assertEquals(counterB.leaveCount(), 1);
+
+        // Remove counterA
+        counterA.dispose();
+
+        // Run it again and check that instrument B is still working but not A
+        assertEquals(13, vm.eval(source).get());
+        assertEquals(counterA.enterCount(), 1);
+        assertEquals(counterA.leaveCount(), 1);
+        assertEquals(counterB.enterCount(), 2);
+        assertEquals(counterB.leaveCount(), 2);
+
+        // Attach a second instrument to the probe
+        counterC.attach(probe);
+
+        // Run the original and check that instruments B,C working but not A
+        assertEquals(13, vm.eval(source).get());
+        assertEquals(counterA.enterCount(), 1);
+        assertEquals(counterA.leaveCount(), 1);
+        assertEquals(counterB.enterCount(), 3);
+        assertEquals(counterB.leaveCount(), 3);
+        assertEquals(counterC.enterCount(), 1);
+        assertEquals(counterC.leaveCount(), 1);
+
+        // Remove instrumentC
+        counterC.dispose();
+
+        // Run the original and check that instrument B working but not A,C
+        assertEquals(13, vm.eval(source).get());
+        assertEquals(counterA.enterCount(), 1);
+        assertEquals(counterA.leaveCount(), 1);
+        assertEquals(counterB.enterCount(), 4);
+        assertEquals(counterB.leaveCount(), 4);
+        assertEquals(counterC.enterCount(), 1);
+        assertEquals(counterC.leaveCount(), 1);
+
+        // Remove instrumentB
+        counterB.dispose();
+
+        // Check that no instruments working
+        assertEquals(13, vm.eval(source).get());
+        assertEquals(counterA.enterCount(), 1);
+        assertEquals(counterA.leaveCount(), 1);
+        assertEquals(counterB.enterCount(), 4);
+        assertEquals(counterB.leaveCount(), 4);
+        assertEquals(counterC.enterCount(), 1);
+        assertEquals(counterC.leaveCount(), 1);
+    }
+
+    private interface TestCounter {
+
+        int enterCount();
+
+        int leaveCount();
+
+        void attach(Probe probe);
+
+        void dispose();
+    }
+
+    /**
+     * A counter for the number of times execution enters and leaves a probed AST node.
+     */
+    private class TestSimpleInstrumentCounter implements TestCounter {
+
+        public int enterCount = 0;
+        public int leaveCount = 0;
+        public Instrumenter instrumenter;
+        private ProbeInstrument instrument;
+
+        public TestSimpleInstrumentCounter(Instrumenter instrumenter) {
+            this.instrumenter = instrumenter;
+        }
+
+        @Override
+        public int enterCount() {
+            return enterCount;
+        }
+
+        @Override
+        public int leaveCount() {
+            return leaveCount;
+        }
+
+        @Override
+        public void attach(Probe probe) {
+            instrument = instrumenter.attach(probe, new SimpleInstrumentListener() {
+
+                public void onEnter(Probe p) {
+                    enterCount++;
+                }
+
+                public void onReturnVoid(Probe p) {
+                    leaveCount++;
+                }
+
+                public void onReturnValue(Probe p, Object result) {
+                    leaveCount++;
+                }
+
+                public void onReturnExceptional(Probe p, Throwable exception) {
+                    leaveCount++;
+                }
+            }, "Instrumentation Test Counter");
+        }
+
+        @Override
+        public void dispose() {
+            instrument.dispose();
+        }
+    }
+
+    /**
+     * A counter for the number of times execution enters and leaves a probed AST node.
+     */
+    private class TestStandardInstrumentCounter implements TestCounter {
+
+        public int enterCount = 0;
+        public int leaveCount = 0;
+        public final Instrumenter instrumenter;
+        public ProbeInstrument instrument;
+
+        public TestStandardInstrumentCounter(Instrumenter instrumenter) {
+            this.instrumenter = instrumenter;
+        }
+
+        @Override
+        public int enterCount() {
+            return enterCount;
+        }
+
+        @Override
+        public int leaveCount() {
+            return leaveCount;
+        }
+
+        @Override
+        public void attach(Probe probe) {
+            instrument = instrumenter.attach(probe, new StandardInstrumentListener() {
+
+                public void onEnter(Probe p, Node node, VirtualFrame vFrame) {
+                    enterCount++;
+                }
+
+                public void onReturnVoid(Probe p, Node node, VirtualFrame vFrame) {
+                    leaveCount++;
+                }
+
+                public void onReturnValue(Probe p, Node node, VirtualFrame vFrame, Object result) {
+                    leaveCount++;
+                }
+
+                public void onReturnExceptional(Probe p, Node node, VirtualFrame vFrame, Throwable exception) {
+                    leaveCount++;
+                }
+            }, "Instrumentation Test Counter");
+        }
+
+        @Override
+        public void dispose() {
+            instrument.dispose();
+        }
+    }
+
+    /**
+     * Tags selected nodes on newly constructed ASTs.
+     */
+    private static final class TestASTProber implements NodeVisitor, ASTProber {
+
+        private final Instrumenter instrumenter;
+
+        TestASTProber(Instrumenter instrumenter) {
+            this.instrumenter = instrumenter;
+        }
+
+        @Override
+        public boolean visit(Node node) {
+            if (node instanceof TestLanguageNode) {
+
+                final TestLanguageNode testNode = (TestLanguageNode) node;
+
+                if (node instanceof TestValueNode) {
+                    instrumenter.probe(testNode).tagAs(InstrumentTestTag.VALUE_TAG, null);
+
+                } else if (node instanceof TestAdditionNode) {
+                    instrumenter.probe(testNode).tagAs(InstrumentTestTag.ADD_TAG, null);
+
+                }
+            }
+            return true;
+        }
+
+        @Override
+        public void probeAST(Instrumenter inst, RootNode rootNode) {
+            rootNode.accept(this);
+        }
+    }
+
+    /**
+     * Counts the number of "enter" events at probed nodes using the simplest AST listener.
+     */
+    static final class TestSimpleInstrumentListener extends DefaultSimpleInstrumentListener {
+
+        public int counter = 0;
+
+        @Override
+        public void onEnter(Probe probe) {
+            counter++;
+        }
+    }
+
+    /**
+     * Counts the number of "enter" events at probed nodes using the AST listener.
+     */
+    static final class TestASTInstrumentListener extends DefaultStandardInstrumentListener {
+
+        public int counter = 0;
+
+        @Override
+        public void onEnter(Probe probe, Node node, VirtualFrame vFrame) {
+            counter++;
+        }
+    }
+
+    private static final class TestProbeListener extends DefaultProbeListener {
+
+        public int probeCount = 0;
+        public int tagCount = 0;
+
+        @Override
+        public void newProbeInserted(Probe probe) {
+            probeCount++;
+        }
+
+        @Override
+        public void probeTaggedAs(Probe probe, SyntaxTag tag, Object tagValue) {
+            tagCount++;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/instrument/InstrumentationTestNodes.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) 2014, 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.instrument;
+
+import com.oracle.truffle.api.CallTarget;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.NodeCost;
+import com.oracle.truffle.api.nodes.NodeInfo;
+import com.oracle.truffle.api.nodes.RootNode;
+
+/**
+ * Tests instrumentation where a client can attach a node that gets attached into the AST.
+ */
+class InstrumentationTestNodes {
+
+    abstract static class TestLanguageNode extends Node {
+        public abstract Object execute(VirtualFrame vFrame);
+
+    }
+
+    @NodeInfo(cost = NodeCost.NONE)
+    static class TestLanguageWrapperNode extends TestLanguageNode implements WrapperNode {
+        @Child private TestLanguageNode child;
+        @Child private EventHandlerNode eventHandlerNode;
+
+        public TestLanguageWrapperNode(TestLanguageNode child) {
+            assert !(child instanceof TestLanguageWrapperNode);
+            this.child = child;
+        }
+
+        @Override
+        public String instrumentationInfo() {
+            return "Wrapper node for testing";
+        }
+
+        @Override
+        public void insertEventHandlerNode(EventHandlerNode eventHandler) {
+            this.eventHandlerNode = eventHandler;
+        }
+
+        @Override
+        public Probe getProbe() {
+            return eventHandlerNode.getProbe();
+        }
+
+        @Override
+        public Node getChild() {
+            return child;
+        }
+
+        @Override
+        public Object execute(VirtualFrame vFrame) {
+            eventHandlerNode.enter(child, vFrame);
+            Object result;
+            try {
+                result = child.execute(vFrame);
+                eventHandlerNode.returnValue(child, vFrame, result);
+            } catch (Exception e) {
+                eventHandlerNode.returnExceptional(child, vFrame, e);
+                throw (e);
+            }
+            return result;
+        }
+    }
+
+    /**
+     * A simple node for our test language to store a value.
+     */
+    static class TestValueNode extends TestLanguageNode {
+        private final int value;
+
+        public TestValueNode(int value) {
+            this.value = value;
+        }
+
+        @Override
+        public Object execute(VirtualFrame vFrame) {
+            return new Integer(this.value);
+        }
+    }
+
+    /**
+     * A node for our test language that adds up two {@link TestValueNode}s.
+     */
+    static class TestAdditionNode extends TestLanguageNode {
+        @Child private TestLanguageNode leftChild;
+        @Child private TestLanguageNode rightChild;
+
+        public TestAdditionNode(TestValueNode leftChild, TestValueNode rightChild) {
+            this.leftChild = insert(leftChild);
+            this.rightChild = insert(rightChild);
+        }
+
+        @Override
+        public Object execute(VirtualFrame vFrame) {
+            return new Integer(((Integer) leftChild.execute(vFrame)).intValue() + ((Integer) rightChild.execute(vFrame)).intValue());
+        }
+    }
+
+    /**
+     * Truffle requires that all guest languages to have a {@link RootNode} which sits atop any AST
+     * of the guest language. This is necessary since creating a {@link CallTarget} is how Truffle
+     * completes an AST. The root nodes serves as our entry point into a program.
+     */
+    static class InstrumentationTestRootNode extends RootNode {
+        @Child private TestLanguageNode body;
+
+        /**
+         * This constructor emulates the global machinery that applies registered probers to every
+         * newly created AST. Global registry is not used, since that would interfere with other
+         * tests run in the same environment.
+         */
+        public InstrumentationTestRootNode(TestLanguageNode body) {
+            super(InstrumentationTestingLanguage.class, null, null);
+            this.body = body;
+        }
+
+        @Override
+        public Object execute(VirtualFrame vFrame) {
+            return body.execute(vFrame);
+        }
+
+        @Override
+        public boolean isCloningAllowed() {
+            return true;
+        }
+    }
+
+    /**
+     * Truffle requires that all guest languages to have a {@link RootNode} which sits atop any AST
+     * of the guest language. This is necessary since creating a {@link CallTarget} is how Truffle
+     * completes an AST. The root nodes serves as our entry point into a program.
+     */
+    static class TestRootNode extends RootNode {
+        @Child private TestLanguageNode body;
+
+        final Instrumenter instrumenter;
+
+        /**
+         * This constructor emulates the global machinery that applies registered probers to every
+         * newly created AST. Global registry is not used, since that would interfere with other
+         * tests run in the same environment.
+         */
+        public TestRootNode(TestLanguageNode body, Instrumenter instrumenter) {
+            super(InstrumentationTestingLanguage.class, null, null);
+            this.instrumenter = instrumenter;
+            this.body = body;
+        }
+
+        @Override
+        public Object execute(VirtualFrame vFrame) {
+            return body.execute(vFrame);
+        }
+
+        @Override
+        public boolean isCloningAllowed() {
+            return true;
+        }
+    }
+
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/instrument/InstrumentationTestingLanguage.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,175 @@
+/*
+ * Copyright (c) 2014, 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.instrument;
+
+import java.io.IOException;
+
+import com.oracle.truffle.api.CallTarget;
+import com.oracle.truffle.api.Truffle;
+import com.oracle.truffle.api.TruffleLanguage;
+import com.oracle.truffle.api.TruffleRuntime;
+import com.oracle.truffle.api.frame.MaterializedFrame;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.InstrumentationTestRootNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestAdditionNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestLanguageNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestLanguageWrapperNode;
+import com.oracle.truffle.api.instrument.InstrumentationTestNodes.TestValueNode;
+import com.oracle.truffle.api.nodes.Node;
+import com.oracle.truffle.api.nodes.NodeVisitor;
+import com.oracle.truffle.api.nodes.RootNode;
+import com.oracle.truffle.api.source.Source;
+
+@TruffleLanguage.Registration(name = "instrumentationTestLanguage", version = "0", mimeType = "text/x-instTest")
+public final class InstrumentationTestingLanguage extends TruffleLanguage<Object> {
+
+    public static final InstrumentationTestingLanguage INSTANCE = new InstrumentationTestingLanguage();
+
+    private static final String ADD_SOURCE_TEXT = "Fake source text for testing:  parses to 6 + 7";
+    private static final String CONSTANT_SOURCE_TEXT = "Fake source text for testing: parses to 42";
+
+    /** Use a unique test name to avoid unexpected CallTarget sharing. */
+    static Source createAdditionSource13(String testName) {
+        return Source.fromText(ADD_SOURCE_TEXT, testName).withMimeType("text/x-instTest");
+    }
+
+    /** Use a unique test name to avoid unexpected CallTarget sharing. */
+    static Source createConstantSource42(String testName) {
+        return Source.fromText(CONSTANT_SOURCE_TEXT, testName).withMimeType("text/x-instTest");
+    }
+
+    static enum InstrumentTestTag implements SyntaxTag {
+
+        ADD_TAG("addition", "test language addition node"),
+
+        VALUE_TAG("value", "test language value node");
+
+        private final String name;
+        private final String description;
+
+        private InstrumentTestTag(String name, String description) {
+            this.name = name;
+            this.description = description;
+        }
+
+        public String getName() {
+            return name;
+        }
+
+        public String getDescription() {
+            return description;
+        }
+    }
+
+    private InstrumentationTestingLanguage() {
+    }
+
+    @Override
+    protected CallTarget parse(Source source, Node context, String... argumentNames) throws IOException {
+        if (source.getCode().equals(ADD_SOURCE_TEXT)) {
+            final TestValueNode leftValueNode = new TestValueNode(6);
+            final TestValueNode rightValueNode = new TestValueNode(7);
+            final TestAdditionNode addNode = new TestAdditionNode(leftValueNode, rightValueNode);
+            final InstrumentationTestRootNode rootNode = new InstrumentationTestRootNode(addNode);
+            final TruffleRuntime runtime = Truffle.getRuntime();
+            final CallTarget callTarget = runtime.createCallTarget(rootNode);
+            return callTarget;
+        }
+        if (source.getCode().equals(CONSTANT_SOURCE_TEXT)) {
+            final TestValueNode constantNode = new TestValueNode(42);
+            final InstrumentationTestRootNode rootNode = new InstrumentationTestRootNode(constantNode);
+            final TruffleRuntime runtime = Truffle.getRuntime();
+            final CallTarget callTarget = runtime.createCallTarget(rootNode);
+            return callTarget;
+        }
+        return null;
+    }
+
+    @Override
+    protected Object findExportedSymbol(Object context, String globalName, boolean onlyExplicit) {
+        return null;
+    }
+
+    @Override
+    protected Object getLanguageGlobal(Object context) {
+        return null;
+    }
+
+    @Override
+    protected boolean isObjectOfLanguage(Object object) {
+        return false;
+    }
+
+    @Override
+    protected Visualizer getVisualizer() {
+        return null;
+    }
+
+    @Override
+    protected boolean isInstrumentable(Node node) {
+        return node instanceof TestAdditionNode || node instanceof TestValueNode;
+    }
+
+    @Override
+    protected WrapperNode createWrapperNode(Node node) {
+        if (isInstrumentable(node)) {
+            return new TestLanguageWrapperNode((TestLanguageNode) node);
+        }
+        return null;
+    }
+
+    @Override
+    protected Object evalInContext(Source source, Node node, MaterializedFrame mFrame) throws IOException {
+        return null;
+    }
+
+    @Override
+    protected Object createContext(Env env) {
+        return null;
+    }
+
+    static final class TestASTProber implements ASTProber {
+
+        public void probeAST(final Instrumenter instrumenter, RootNode startNode) {
+            startNode.accept(new NodeVisitor() {
+
+                @Override
+                public boolean visit(Node node) {
+                    if (node instanceof TestLanguageNode) {
+
+                        final TestLanguageNode testNode = (TestLanguageNode) node;
+
+                        if (node instanceof TestValueNode) {
+                            instrumenter.probe(testNode).tagAs(InstrumentTestTag.VALUE_TAG, null);
+
+                        } else if (node instanceof TestAdditionNode) {
+                            instrumenter.probe(testNode).tagAs(InstrumentTestTag.ADD_TAG, null);
+
+                        }
+                    }
+                    return true;
+                }
+            });
+        }
+    }
+
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/interop/ForeignAccessSingleThreadedTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2012, 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.interop;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.oracle.truffle.api.CallTarget;
+import com.oracle.truffle.api.nodes.Node;
+
+public class ForeignAccessSingleThreadedTest implements ForeignAccess.Factory, TruffleObject {
+    ForeignAccess fa;
+    private int cnt;
+
+    @Before
+    public void initInDifferentThread() throws InterruptedException {
+        Thread t = new Thread("Initializer") {
+            @Override
+            public void run() {
+                fa = ForeignAccess.create(ForeignAccessSingleThreadedTest.this);
+            }
+        };
+        t.start();
+        t.join();
+    }
+
+    @Test(expected = AssertionError.class)
+    public void accessNodeFromWrongThread() {
+        Node n = Message.IS_EXECUTABLE.createNode();
+        Object ret = ForeignAccess.execute(n, null, this);
+        fail("Should throw an exception: " + ret);
+    }
+
+    @After
+    public void noCallsToFactory() {
+        assertEquals("No calls to accessMessage or canHandle", 0, cnt);
+    }
+
+    @Override
+    public boolean canHandle(TruffleObject obj) {
+        cnt++;
+        return true;
+    }
+
+    @Override
+    public CallTarget accessMessage(Message tree) {
+        cnt++;
+        return null;
+    }
+
+    @Override
+    public ForeignAccess getForeignAccess() {
+        return fa;
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/interop/ForeignAccessToStringTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) 2012, 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.interop;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+import com.oracle.truffle.api.CallTarget;
+
+public class ForeignAccessToStringTest {
+    @Test
+    public void checkRegularFactory() {
+        ForeignAccess fa = ForeignAccess.create(new SimpleTestingFactory());
+        assertEquals("ForeignAccess[" + ForeignAccessToStringTest.class.getName() + "$SimpleTestingFactory]", fa.toString());
+    }
+
+    @Test
+    public void check10Factory() {
+        ForeignAccess fa = ForeignAccess.create(TruffleObject.class, new Simple10TestingFactory());
+        assertEquals("ForeignAccess[" + ForeignAccessToStringTest.class.getName() + "$Simple10TestingFactory]", fa.toString());
+    }
+
+    private static class SimpleTestingFactory implements ForeignAccess.Factory {
+        public SimpleTestingFactory() {
+        }
+
+        @Override
+        public boolean canHandle(TruffleObject obj) {
+            return false;
+        }
+
+        @Override
+        public CallTarget accessMessage(Message tree) {
+            return null;
+        }
+    }
+
+    private static class Simple10TestingFactory implements ForeignAccess.Factory10 {
+        @Override
+        public CallTarget accessIsNull() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessIsExecutable() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessIsBoxed() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessHasSize() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessGetSize() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessUnbox() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessRead() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessWrite() {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessExecute(int argumentsLength) {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessInvoke(int argumentsLength) {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessMessage(Message unknown) {
+            return null;
+        }
+
+        @Override
+        public CallTarget accessNew(int argumentsLength) {
+            return null;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/interop/MessageStringTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2012, 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.interop;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.util.Locale;
+
+import org.junit.Test;
+
+public class MessageStringTest {
+
+    @Test
+    public void testFields() throws Exception {
+        for (Field f : Message.class.getFields()) {
+            if (f.getType() != Message.class) {
+                continue;
+            }
+            if ((f.getModifiers() & Modifier.STATIC) == 0) {
+                continue;
+            }
+            Message msg = (Message) f.get(null);
+
+            String persistent = Message.toString(msg);
+            assertNotNull("Found name for " + f, persistent);
+            assertEquals("It is in upper case", persistent, persistent.toUpperCase(Locale.ENGLISH));
+
+            Message newMsg = Message.valueOf(persistent);
+
+            assertSame("Same for " + f, msg, newMsg);
+
+            assertEquals("Same toString()", persistent, msg.toString());
+        }
+    }
+
+    @Test
+    public void testFactoryMethods() throws Exception {
+        for (Method m : Message.class.getMethods()) {
+            if (m.getReturnType() != Message.class) {
+                continue;
+            }
+            if (!m.getName().startsWith("create")) {
+                continue;
+            }
+            if ((m.getModifiers() & Modifier.STATIC) == 0) {
+                continue;
+            }
+            Message msg = (Message) m.invoke(null, 0);
+
+            String persistent = Message.toString(msg);
+            assertNotNull("Found name for " + m, persistent);
+            assertEquals("It is in upper case", persistent, persistent.toUpperCase(Locale.ENGLISH));
+
+            Message newMsg = Message.valueOf(persistent);
+
+            assertEquals("Same for " + m, msg, newMsg);
+
+            assertEquals("Same toString()", persistent, msg.toString());
+            assertEquals("Same toString() for new one", persistent, newMsg.toString());
+        }
+    }
+
+    @Test
+    public void specialMessagePersitance() {
+        SpecialMsg msg = new SpecialMsg();
+        String persistent = Message.toString(msg);
+        Message newMsg = Message.valueOf(persistent);
+        assertEquals("Message reconstructed", msg, newMsg);
+    }
+
+    public static final class SpecialMsg extends Message {
+
+        @Override
+        public boolean equals(Object message) {
+            return message instanceof SpecialMsg;
+        }
+
+        @Override
+        public int hashCode() {
+            return 5425432;
+        }
+    }
+}

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/nodes/NodeUtilTest.java	Fri Dec 04 11:33:08 2015 +0100
@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2012, 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.nodes;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.junit.Assert.assertThat;
+
+import java.util.Iterator;
+
+import org.junit.Test;
+
+import com.oracle.truffle.api.TestingLanguage;
+import com.oracle.truffle.api.frame.VirtualFrame;
+
+public class NodeUtilTest {
+
+    @Test
+    public void testRecursiveIterator1() {
+        TestRootNode root = new TestRootNode();
+        root.child0 = new TestNode();
+        root.adoptChildren();
+
+        int count = iterate(NodeUtil.makeRecursiveIterator(root));
+
+        assertThat(count, is(2));
+        assertThat(root.visited, is(0));
+        assertThat(root.child0.visited, is(1));
+    }
+
+    private static int iterate(Iterator<Node> iterator) {
+        int iterationCount = 0;
+        while (iterator.hasNext()) {
+            Node node = iterator.next();
+            if (node == null) {
+                continue;
+            }
+            if (node instanceof TestNode) {
+                ((TestNode) node).visited = iterationCount;
+            } else if (node instanceof TestRootNode) {
+                ((TestRootNode) node).visited = iterationCount;
+            } else {
+                throw new AssertionError();
+            }
+            iterationCount++;
+        }
+        return iterationCount;
+    }
+
+    private static class TestNode extends Node {
+
+        @Child TestNode child0;
+        @Child TestNode child1;
+
+        private int visited;
+
+        public TestNode() {
+        }
+
+    }
+
+    private static class TestRootNode extends RootNode {
+
+        @Child TestNode child0;
+
+        private int visited;
+
+        public TestRootNode() {
+            super(TestingLanguage.class, null, null);
+        }
+
+        @Override
+        public Object execute(VirtualFrame frame) {
+            return null;
+        }
+
+    }
+
+}