Add instrumentation tutorial; fix a few typos and annotation processor bugs

Author: DSouzaM

truffle/docs/bytecode_dsl/BytecodeDSL.md

@@ -100,7 +100,7 @@ The Bytecode DSL supports a variety of features, including:
 
 - **Serialization**: Bytecode DSL interpreters support serialization/deserialization, which enables a language to persist the bytecode for a guest program and reconstruct it without reprocessing the source program (see the [Serialization tutorial][serialization]).
 
-- **Instrumentation**: Bytecode DSL interpreters support special instrumentation operations and tag-based instrumentation.
+- **Instrumentation**: Bytecode DSL interpreters support special instrumentation operations and tag-based instrumentation (see the [Instrumentation tutorial][instrumentation]).
 
 - **Lazy source and instrumentation metadata**: Source and instrumentation metadata increase the footprint of the interpreter. By default, Bytecode DSL interpreters elide this metadata when building bytecode, so they have no footprint overhead when they are not used. The metadata is recomputed on demand by replaying the builder calls.
 
@@ -122,4 +122,5 @@ The Bytecode DSL implementation for [SimpleLanguage](https://github.com/oracle/g
 
 
 [serialization]: https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/SerializationTutorial.java
-[continuations]: https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/ContinuationsTutorial.java
+[continuations]: https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/ContinuationsTutorial.java
+[instrumentation]: https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/InstrumentationTutorial.java

truffle/docs/bytecode_dsl/UserGuide.md

@@ -538,7 +538,7 @@ Take extra care if accessing source information in [compiled code](RuntimeCompil
 ### Instrumentation
 
 The behaviour of a Bytecode DSL interpreter can be non-intrusively observed (and modified) using instrumentation.
-For example, you can instrument your code to trace each guest language statement, or add instrumentation to log return values.
+For example, you can instrument your code to trace each guest language statement, or add instrumentation to log return values (see the [Instrumentation tutorial](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/InstrumentationTutorial.java) for more details).
 
 Instrumentations are specified during parsing, but disabled by default.
 They incur no overhead until they are enabled at a later time (see [Reparsing metadata](#reparsing)).

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/InstrumentationTest.java

@@ -609,6 +609,18 @@ public static int doInt(@SuppressWarnings("unused") @Variadic Object... args) {
             }
         }
 
+        @ExpectError("An @Instrumentation operation cannot be void and also specify a dynamic operand. " + //
+                        "Instrumentations must have transparent stack effects. " +
+                        "Change the return type or remove the dynamic operand to resolve this.")
+        @Instrumentation
+        static final class InvalidInstrumentation4 {
+
+            @Specialization
+            public static void doInt(@SuppressWarnings("unused") Object arg) {
+                return;
+            }
+        }
+
     }
 
     @GenerateBytecode(languageClass = BytecodeInstrumentationTestLanguage.class, //

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/TagTest.java

@@ -2891,7 +2891,7 @@ protected Object createContext(Env env) {
 
     }
 
-    @ExpectError("Tag instrumentation uses implicit root tagging, but the RootTag was not provded by the language class 'com.oracle.truffle.api.bytecode.test.TagTest.NoRootTagTestLanguage'. " +
+    @ExpectError("Tag instrumentation uses implicit root tagging, but the RootTag was not provided by the language class 'com.oracle.truffle.api.bytecode.test.TagTest.NoRootTagTestLanguage'. " +
                     "Specify the tag using @ProvidedTags(RootTag.class) on the language class or explicitly disable root tagging using @GenerateBytecode(.., enableRootTagging=false) to resolve this.")
     @GenerateBytecode(languageClass = NoRootTagTestLanguage.class, //
                     enableTagInstrumentation = true)
@@ -2944,7 +2944,7 @@ protected Object createContext(Env env) {
 
     }
 
-    @ExpectError("Tag instrumentation uses implicit root body tagging, but the RootTag was not provded by the language class 'com.oracle.truffle.api.bytecode.test.TagTest.NoRootBodyTagTestLanguage'. " +
+    @ExpectError("Tag instrumentation uses implicit root body tagging, but the RootTag was not provided by the language class 'com.oracle.truffle.api.bytecode.test.TagTest.NoRootBodyTagTestLanguage'. " +
                     "Specify the tag using @ProvidedTags(RootBodyTag.class) on the language class or explicitly disable root tagging using @GenerateBytecode(.., enableRootBodyTagging=false) to resolve this.")
     @GenerateBytecode(languageClass = NoRootBodyTagTestLanguage.class, //
                     enableTagInstrumentation = true)

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/error_tests/ErrorTests.java

@@ -934,7 +934,7 @@ static int sub(int x, int y) {
     }
 
     @GenerateBytecode(languageClass = ErrorLanguage.class)
-    @ExpectError({"At least one operation must be declared using @Operation, @OperationProxy, or @ShortCircuitOperation."})
+    @ExpectWarning("No custom operations were declared. Custom operations can be declared using @Operation, @OperationProxy, or @ShortCircuitOperation.")
     public abstract static class NoOperationsTest extends RootNode implements BytecodeRootNode {
         protected NoOperationsTest(ErrorLanguage language, FrameDescriptor builder) {
             super(language, builder);