Instrumenter to observe behavior of nodes with UUID

CHANGELOG.md

@@ -969,6 +969,7 @@
 - [Merge `Small_Integer` and `Big_Integer` types][7636]
 - [Inline type ascriptions][7796]
 - [Always persist `TRACE` level logs to a file][7825]
+- [Meta.instrument & Instrumentor API][7833]
 - [Downloadable VSCode extension][7861]
 - [New `project/status` route for reporting LS state][7801]
 - [Add Enso-specific assertions][7883])
@@ -1116,6 +1117,7 @@
 [7796]: https://github.com/enso-org/enso/pull/7796
 [7801]: https://github.com/enso-org/enso/pull/7801
 [7825]: https://github.com/enso-org/enso/pull/7825
+[7833]: https://github.com/enso-org/enso/pull/7833
 [7861]: https://github.com/enso-org/enso/pull/7861
 [7883]: https://github.com/enso-org/enso/pull/7883
 [7840]: https://github.com/enso-org/enso/pull/7840

distribution/lib/Standard/Base/0.0.0-dev/src/Meta.enso

@@ -12,7 +12,9 @@ import project.Data.Vector.Vector
 import project.Error.Error as Base_Error
 import project.Errors.Common.Not_Found
 import project.Nothing.Nothing
+import project.Function.Function
 import project.Polyglot.Java
+from project.Runtime.Managed_Resource import Managed_Resource
 from project.Data.Boolean import Boolean, False, True
 
 type Type
@@ -212,6 +214,13 @@ type Unresolved_Symbol
     scope : Any
     scope self = get_unresolved_symbol_scope self.value
 
+    ## ADVANCED
+       GROUP Metadata
+
+       Starts building an instrumentation for a given node
+    instrument : Instrumentor
+    instrument self = Instrumentor.Value (instrumentor_builtin "newBuilder" [ self.value ])
+
 type Error
     ## PRIVATE
        ADVANCED
@@ -579,6 +588,72 @@ get_short_type_name typ = @Builtin_Method "Meta.get_short_type_name"
 get_constructor_declaring_type : Any -> Any
 get_constructor_declaring_type constructor = @Builtin_Method "Meta.get_constructor_declaring_type"
 
+instrumentor_builtin op args = @Builtin_Method "Meta.instrumentor_builtin"
+
+## PRIVATE
+   ADVANCED
+
+   Builder to create instrumentation for a function
+type Instrumentor
+    ## PRIVATE
+    Value impl
+
+    ## PRIVATE
+       ADVANCED
+
+       Registers callback to be executed at the begining of node/expression
+       execution. The callback `fn` gets UUID of the node/expression that is
+       being executed and can return `Nothing` to continue regular execution
+       or anything else to skip the execution and just return given value.
+
+       Arguments:
+       - fn: The callback function accepting UUID.
+    on_enter self (fn : Text -> Any | Nothing) =
+        new = instrumentor_builtin "onEnter" [ self.impl, fn ]
+        Instrumentor.Value new
+
+    ## PRIVATE
+       ADVANCED
+
+       Registers callback to be executed when a node/expression evaluation
+       is over. The callback `fn` gets UUID and the computed value. Usually
+       the value is _cached_ and returned from `on_enter` callback next time
+       the same expression is evaluated.
+
+       Arguments:
+       - fn: The callback function accepting UUID and computed value
+    on_return self (fn : Text -> Any -> Nothing) =
+        new = instrumentor_builtin "onReturn" [ self.impl, fn ]
+        Instrumentor.Value new
+
+    ## PRIVATE
+       ADVANCED
+
+       Registers callback to be executed when a node/expression representing function is about to be called.
+       The callback `fn` shall accept three arguments. The UUID to identify the expression, the function to be
+       invoked and the arguments to pass to the function. The callback can return `Nothing`
+       (in such case the function gets executed with provided arguments) or some other value,
+       which is then returned instead of calling the function.
+
+       Arguments:
+       - fn: The callback function accepting UUID and function value
+    on_call self (fn : Text -> Function -> Vector Any -> Any | Nothing) =
+        new = instrumentor_builtin "onCall" [ self.impl, fn ]
+        Instrumentor.Value new
+
+    ## PRIVATE
+       ADVANCED
+
+       Activates configured instrumentor. Returns managed resource to
+       deactivate the instrumentor later.
+
+       Arguments:
+       - value: The value of the atom in the meta representation.
+    activate self =
+        finalize_instrumentor impl = instrumentor_builtin "deactivate" [ impl ]
+        create action = (instrumentor_builtin action [ self.impl, finalize_instrumentor ]) : Managed_Resource
+        create "activate"
+
 ## PRIVATE
    Returns type specified by fully qualified name.
 

engine/polyglot-api/src/main/java/org/enso/polyglot/debugger/IdExecutionService.java

@@ -0,0 +1,55 @@
+package org.enso.polyglot.debugger;
+
+import com.oracle.truffle.api.CallTarget;
+import com.oracle.truffle.api.instrumentation.EventBinding;
+import com.oracle.truffle.api.instrumentation.ExecutionEventNodeFactory;
+import com.oracle.truffle.api.interop.TruffleObject;
+import java.util.UUID;
+
+public interface IdExecutionService {
+  String INSTRUMENT_ID = "id-value-extractor";
+
+  public interface Callbacks {
+    /**
+     * Finds out previously computed result for given id. If a result is returned, then the
+     * execution of given node is skipped and the value is returned back.
+     *
+     * @param nodeId identification of the node to be computed
+     * @return {@code null} should the execution of the node be performed; any other value to skip
+     *     the execution and return the value as a result.
+     */
+    Object findCachedResult(UUID nodeId);
+
+    /**
+     * Notifies when an execution of a node is over.
+     *
+     * @param nodeId identification of the node to be computed
+     * @param result the just computed result
+     * @param isPanic was the result a panic?
+     * @param nanoElapsedTime how long it took to compute the result?
+     */
+    void updateCachedResult(UUID nodeId, Object result, boolean isPanic, long nanoElapsedTime);
+
+    /**
+     * Notification when a returned value is a function.
+     *
+     * @param nodeId identification of the node to be computed
+     * @param result info about function call
+     * @return {@code null} should the execution of the node be performed; any other value to skip
+     *     the execution and return the value as a result.
+     */
+    Object onFunctionReturn(UUID nodeId, TruffleObject result);
+  }
+
+  /**
+   * Attach a new event node factory to observe identified nodes within given function.
+   *
+   * @param module module that contains the code
+   * @param entryCallTarget the call target being observed.
+   * @param callbacks the interface to receive notifications
+   * @param timer the execution timer.
+   * @return a reference to the attached event node factory.
+   */
+  EventBinding<ExecutionEventNodeFactory> bind(
+      TruffleObject module, CallTarget entryCallTarget, Callbacks callbacks, Object timer);
+}