[GR-77583] Add Bytecode DSL instrumentation value interception.

PullRequest: graal/24736

Author: chumer

truffle/CHANGELOG.md

@@ -3,6 +3,7 @@
 This changelog summarizes major changes between Truffle versions relevant to languages implementors building upon the Truffle framework. The main focus is on APIs exported by Truffle.
 
 ## Version 25.2
+* GR-77583: Bytecode DSL: Added `BytecodeRootNode.interceptIncomingValue(Object)` and `BytecodeRootNode.interceptOutgoingValue(Object)` to convert values exchanged with tag instrumentation.
 * GR-75459: Bytecode DSL: Added multi-operand support for `@Yield` operations.
 * GR-75438: Bytecode DSL: Added `@Return` for user-defined return operations that customize the value returned from a bytecode root node.
 * GR-77108: Added `HostCompilerDirectives.BytecodeInterpreterHandlerConfig#secondarySwitch()` to prevent handler outlining when a secondary bytecode interpreter switch is compiled separately.

truffle/docs/bytecode_dsl/UserGuide.md

@@ -554,6 +554,8 @@ The Bytecode DSL supports two forms of instrumentation:
 1. [`@Instrumentation`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/Instrumentation.java) operations, which are emitted and behave just like custom [`@Operation`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/Operation.java)s. These operations can perform special actions like logging or modifying the value produced by another operation. `@Instrumentation` operations must have no stack effects, so they can either have no children and produce no value, or have one child and produce a value (which allows you to modify the result of an instrumented operation).
 2. Tag-based instrumentation associates operations with particular instrumentation [`Tag`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.instrumentation/src/com/oracle/truffle/api/instrumentation/Tag.java)s using `Tag` operations. If these instrumentations are enabled, the bytecode will include instructions that invoke the various event callbacks on any attached [`ExecutionEventNode`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.instrumentation/src/com/oracle/truffle/api/instrumentation/ExecutionEventNode.java)s (e.g., `onEnter`, `onReturnValue`) when executing the enclosed operation. Tag-based instrumentation can be enabled using the `enableTagInstrumentation` flag in [`@GenerateBytecode`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/GenerateBytecode.java).
 
+Override [`BytecodeRootNode.interceptOutgoingValue`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/BytecodeRootNode.java) to convert every guest-language value before it is exposed to tag instrumentation, for example to replace an internal representation with an interop-capable value. Override [`BytecodeRootNode.interceptIncomingValue`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/BytecodeRootNode.java) to convert values supplied by tag instrumentation to representations supported by the guest language. The hooks add no generated calls unless they are overridden and do not apply to `@Instrumentation` operations.
+
 Note: once instrumentation instructions are added, they cannot be removed from the bytecode. However, in tag-based instrumentation you can still disable the instruments so that the instrumentation instructions have no effect.
 
 ### Reparsing

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

@@ -155,6 +155,25 @@ protected UnusedUncachedThreshold(ErrorLanguage language, FrameDescriptor frameD
         }
     }
 
+    @GenerateBytecode(languageClass = ErrorLanguage.class)
+    public abstract static class InterceptionWithoutTagInstrumentation extends RootNode implements BytecodeRootNode {
+        protected InterceptionWithoutTagInstrumentation(ErrorLanguage language, FrameDescriptor frameDescriptor) {
+            super(language, frameDescriptor);
+        }
+
+        @ExpectError("interceptIncomingValue can only be overridden when tag instrumentation is enabled. Enable tag instrumentation or remove this override.")
+        @Override
+        public Object interceptIncomingValue(Object value) {
+            return value;
+        }
+
+        @ExpectError("interceptOutgoingValue can only be overridden when tag instrumentation is enabled. Enable tag instrumentation or remove this override.")
+        @Override
+        public Object interceptOutgoingValue(Object value) {
+            return value;
+        }
+    }
+
     @ExpectError("Error parsing expression%")
     @GenerateBytecode(languageClass = ErrorLanguage.class, enableUncachedInterpreter = true, defaultUncachedThreshold = "-1")
     public abstract static class BadUncachedThreshold extends RootNode implements BytecodeRootNode {

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

@@ -221,6 +221,8 @@ meth public com.oracle.truffle.api.source.Source getSource()
 meth public com.oracle.truffle.api.source.SourceSection ensureSourceSection()
 meth public com.oracle.truffle.api.source.SourceSection ensureSourceSectionWithContent()
 meth public java.lang.Object interceptControlFlowException(com.oracle.truffle.api.nodes.ControlFlowException,com.oracle.truffle.api.frame.VirtualFrame,com.oracle.truffle.api.bytecode.BytecodeNode,int) throws java.lang.Throwable
+meth public java.lang.Object interceptIncomingValue(java.lang.Object)
+meth public java.lang.Object interceptOutgoingValue(java.lang.Object)
 meth public java.lang.String dump()
 meth public java.lang.Throwable interceptInternalException(java.lang.Throwable,com.oracle.truffle.api.frame.VirtualFrame,com.oracle.truffle.api.bytecode.BytecodeNode,int)
 meth public void traceTransition(com.oracle.truffle.api.bytecode.BytecodeTransition,com.oracle.truffle.api.frame.Frame)

truffle/src/com.oracle.truffle.api.bytecode/snapshot.sigtest

@@ -45,6 +45,9 @@
 import com.oracle.truffle.api.exception.AbstractTruffleException;
 import com.oracle.truffle.api.frame.Frame;
 import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.instrumentation.EventContext;
+import com.oracle.truffle.api.instrumentation.ExecutionEventListener;
+import com.oracle.truffle.api.instrumentation.ExecutionEventNode;
 import com.oracle.truffle.api.nodes.ControlFlowException;
 import com.oracle.truffle.api.source.Source;
 import com.oracle.truffle.api.source.SourceSection;
@@ -80,6 +83,45 @@ public interface BytecodeRootNode {
      */
     Object execute(VirtualFrame frame);
 
+    /**
+     * Optional hook invoked to convert a value received from tag instrumentation before it resumes
+     * guest-language execution. Instruments can introduce values by returning a non-{@code null}
+     * value from an unwind callback such as
+     * {@link ExecutionEventNode#onUnwind(VirtualFrame, Object)} or
+     * {@link ExecutionEventListener#onUnwind(EventContext, VirtualFrame, Object)}. Such values are
+     * interop values and may need to be converted to a representation supported by the guest
+     * language.
+     *
+     * @param value the interop value received from tag instrumentation
+     * @return the value to resume execution with
+     * @see EventContext#createUnwind(Object)
+     * @since 25.2
+     */
+    @SuppressWarnings("unused")
+    default Object interceptIncomingValue(Object value) {
+        return value;
+    }
+
+    /**
+     * Optional hook invoked to convert every guest-language value before it is exposed to tag
+     * instrumentation. This can be used to replace an internal representation with an
+     * interop-capable value. The original value continues to be used for guest-language execution.
+     * <p>
+     * The returned value must be an interop value or {@code null}. For values reported after
+     * successful execution of a standard tag, this requirement is checked when Java assertions are
+     * enabled, and a violation results in a {@link ClassCastException}. Values not subject to this
+     * check are passed to tag instrumentation unchanged. The hook is not invoked when the
+     * instrumented operation does not produce a value.
+     *
+     * @param value the guest-language value being exposed to tag instrumentation
+     * @return the interop value to report to tag instrumentation
+     * @since 25.2
+     */
+    @SuppressWarnings("unused")
+    default Object interceptOutgoingValue(Object value) {
+        return value;
+    }
+
     /**
      * Optional hook invoked when a {@link ControlFlowException} is thrown during execution. This
      * hook can do one of four things:

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/BytecodeRootNode.java

@@ -1536,6 +1536,14 @@ private TypeMirror emitLoadException(CodeTreeBuilder b, String resultLocalName)
         return type(Throwable.class);
     }
 
+    private void emitOutgoingValue(CodeTreeBuilder b, String value) {
+        if (model().interceptOutgoingValue == null) {
+            b.string(value);
+        } else {
+            b.startCall("getRoot()", model().interceptOutgoingValue).string(value).end();
+        }
+    }
+
     private TypeMirror emitTagLeave(CodeTreeBuilder b, ExecutionMode mode) {
         Operand valueOperand = instruction.signature.singleDynamicOperand();
         if (mode.isFastPath()) {
@@ -1545,7 +1553,7 @@ private TypeMirror emitTagLeave(CodeTreeBuilder b, ExecutionMode mode) {
             b.end();
             b.startStatement().startCall("tagNode.findProbe().onReturnValue");
             b.string(parent.localFrame());
-            b.string(valueOperand.localName());
+            emitOutgoingValue(b, valueOperand.localName());
             b.end().end();
         } else { // slow-path
 
@@ -1607,7 +1615,7 @@ private TypeMirror emitTagLeave(CodeTreeBuilder b, ExecutionMode mode) {
             b.end();
             b.startStatement().startCall("tagNode.findProbe().onReturnValue");
             b.string(parent.localFrame());
-            b.string(valueOperand.localName());
+            emitOutgoingValue(b, valueOperand.localName());
             b.end(2);
         }
         return null;
@@ -1638,7 +1646,7 @@ private TypeMirror emitTagYield(CodeTreeBuilder b) {
 
         b.startStatement().startCall("tagNode.findProbe().onYield");
         b.string(parent.localFrame());
-        b.string("result_");
+        emitOutgoingValue(b, "result_");
         b.end(2);
         return null;
     }

truffle/src/com.oracle.truffle.dsl.processor/src/com/oracle/truffle/dsl/processor/bytecode/generator/BytecodeInstructionHandler.java

@@ -2244,6 +2244,10 @@ private CodeExecutableElement createHandleException() {
                     TypeMirror targetType = entry.getKey();
                     b.startCaseBlock();
 
+                    if (parent.model.interceptIncomingValue != null) {
+                        b.startStatement().string("result = ").startCall("root", parent.model.interceptIncomingValue).string("result").end(2);
+                    }
+
                     CodeExecutableElement expectMethod = null;
                     if (!ElementUtils.isObject(targetType)) {
                         expectMethod = parent.lookupExpectMethod(parent.parserType, targetType);

truffle/src/com.oracle.truffle.dsl.processor/src/com/oracle/truffle/dsl/processor/bytecode/generator/BytecodeNodeElement.java

@@ -185,7 +185,9 @@ public boolean binds(ParameterKind parameter) {
     public ExecutableElement fdConstructor;
     public ExecutableElement fdBuilderConstructor;
     public ExecutableElement interceptControlFlowException;
+    public ExecutableElement interceptIncomingValue;
     public ExecutableElement interceptInternalException;
+    public ExecutableElement interceptOutgoingValue;
     public ExecutableElement interceptTruffleException;
     public ExecutableElement traceTransition;
 

truffle/src/com.oracle.truffle.dsl.processor/src/com/oracle/truffle/dsl/processor/bytecode/model/BytecodeDSLModel.java

@@ -384,10 +384,23 @@ private void parseBytecodeDSLModel(TypeElement typeElement, BytecodeDSLModel mod
 
         // Extract hook implementations.
         model.interceptControlFlowException = ElementUtils.findMethod(typeElement, "interceptControlFlowException");
+        model.interceptIncomingValue = ElementUtils.findMethod(typeElement, "interceptIncomingValue");
         model.interceptInternalException = ElementUtils.findMethod(typeElement, "interceptInternalException");
+        model.interceptOutgoingValue = ElementUtils.findMethod(typeElement, "interceptOutgoingValue");
         model.interceptTruffleException = ElementUtils.findMethod(typeElement, "interceptTruffleException");
         model.traceTransition = ElementUtils.findMethod(typeElement, "traceTransition");
 
+        if (!model.enableTagInstrumentation) {
+            if (model.interceptIncomingValue != null) {
+                model.addError(model.interceptIncomingValue,
+                                "interceptIncomingValue can only be overridden when tag instrumentation is enabled. Enable tag instrumentation or remove this override.");
+            }
+            if (model.interceptOutgoingValue != null) {
+                model.addError(model.interceptOutgoingValue,
+                                "interceptOutgoingValue can only be overridden when tag instrumentation is enabled. Enable tag instrumentation or remove this override.");
+            }
+        }
+
         checkRootNodeOverrides(typeElement, model);
         if (model.hasErrors()) {
             return;