Enhance Managed_Resource to allow implementation of in-memory caches

CHANGELOG.md

@@ -75,13 +75,15 @@
   operation.][11490]
 - [Added `Table.input` allowing creation of typed tables from vectors of data,
   including auto parsing text columns.][11562]
+- [Enhance Managed_Resource to allow implementation of in-memory caches][11577]
 
 [11235]: https://github.com/enso-org/enso/pull/11235
 [11255]: https://github.com/enso-org/enso/pull/11255
 [11371]: https://github.com/enso-org/enso/pull/11371
 [11373]: https://github.com/enso-org/enso/pull/11373
 [11490]: https://github.com/enso-org/enso/pull/11490
 [11562]: https://github.com/enso-org/enso/pull/11562
+[11577]: https://github.com/enso-org/enso/pull/11577
 
 #### Enso Language & Runtime
 

distribution/lib/Standard/Base/0.0.0-dev/src/Runtime/Managed_Resource.enso

@@ -2,6 +2,7 @@
 
 import project.Any.Any
 import project.Nothing.Nothing
+import project.Data.Boolean.Boolean
 
 ## Resource provides an API for manual management of computation resources.
 
@@ -34,17 +35,25 @@ type Managed_Resource
        ADVANCED
 
        Registers a resource with the resource manager to be cleaned up using
-       function once it is no longer in use.
+       function once it is no longer in use. The optional `system_finalization_allowed`
+       flag allow the system to explicitly call `finalize` on the resource
+       when _"needed"_. The definition is intentionally vague, but
+       currently the IDE performs such a call when user requests a _"reload"_ -
+       e.g. using `Managed_Resource.register cache cleanup_fn True` is useful
+       for creating user managed caches.
 
        Arguments:
        - resource: The resource to register.
        - function: The action to be executed on resource to clean it up when
          it is no longer in use.
+       - system_finalization_allowed: is the system allowed to call `finalize`
+         on the resource when "needed"
 
        Returns:
        A `Managed_Resource` object that can be used to access the resource.
-    register : Any -> (Any -> Nothing) -> Managed_Resource
-    register resource function = @Builtin_Method "Managed_Resource.register"
+    register : Any -> (Any -> Nothing) -> Boolean -> Managed_Resource
+    register resource function system_finalization_allowed=Boolean.False =
+        @Tail_Call register_builtin resource function system_finalization_allowed
 
     ## PRIVATE
        ADVANCED
@@ -58,13 +67,19 @@ type Managed_Resource
        ADVANCED
 
        Executes the provided action on the resource managed by the managed
-       resource object.
+       resource object. The action is only invoked if the managed resource
+       has not yet been finalized.
 
        Arguments:
        - action: The action that will be applied to the resource managed by
          resource.
-    with : (Any -> Any) -> Any
-    with self ~action = @Builtin_Method "Managed_Resource.with"
+       - on_missing: Optional action to perform when the value is no longer
+         reachable
+       Returns:
+       Value returned from the `action` or `Nothing` if the managed resource
+       was already finalized
+    with : (Any -> Any) -> Any -> Any
+    with self ~action ~on_missing=Nothing = with_builtin self action on_missing...
 
     ## PRIVATE
        ADVANCED
@@ -74,3 +89,6 @@ type Managed_Resource
        managed resources system.
     take : Any
     take self = @Builtin_Method "Managed_Resource.take"
+
+register_builtin r fn sys:Boolean = @Builtin_Method "Managed_Resource.register_builtin"
+with_builtin r fn ~on_missing = @Builtin_Method "Managed_Resource.with_builtin"

distribution/lib/Standard/Base/0.0.0-dev/src/System/Input_Stream.enso

@@ -4,6 +4,7 @@ import project.Data.Numbers.Integer
 import project.Data.Text.Encoding.Encoding
 import project.Data.Vector.Vector
 import project.Error.Error
+import project.Panic.Panic
 import project.Errors.File_Error.File_Error
 import project.Errors.Illegal_State.Illegal_State
 import project.Errors.Problem_Behavior.Problem_Behavior
@@ -17,6 +18,7 @@ import project.System.File.Generic.Writable_File.Writable_File
 import project.System.Internal.Reporting_Stream_Decoder_Helper
 from project.Data.Boolean import Boolean, False, True
 
+polyglot java import java.io.IOException
 polyglot java import java.io.BufferedInputStream
 polyglot java import java.io.ByteArrayInputStream
 polyglot java import java.io.InputStream as Java_Input_Stream
@@ -114,9 +116,10 @@ type Input_Stream
        Arguments:
        - f: Applies a function over the internal java stream.
     with_java_stream : (Java_Input_Stream -> Any) -> Any
-    with_java_stream self f = self.stream_resource . with java_like_stream->
-        java_stream = Stream_Utils.asInputStream java_like_stream
-        self.error_handler <| f java_stream
+    with_java_stream self f =
+        self.stream_resource . with on_missing=(Panic.throw <| IOException.new "Stream closed") java_like_stream->
+            java_stream = Stream_Utils.asInputStream java_like_stream
+            self.error_handler <| f java_stream
 
     ## PRIVATE
        Runs an action with a `ReportingStreamDecoder` decoding data from the

engine/runtime-integration-tests/src/test/java/org/enso/interpreter/runtime/ManagedResourceTest.java

@@ -0,0 +1,116 @@
+package org.enso.interpreter.runtime;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+import java.lang.ref.Reference;
+import java.lang.ref.WeakReference;
+import org.enso.common.MethodNames;
+import org.enso.test.utils.ContextUtils;
+import org.graalvm.polyglot.Context;
+import org.graalvm.polyglot.Source;
+import org.graalvm.polyglot.Value;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class ManagedResourceTest {
+  private static Context ctx;
+  private static EnsoContext ensoCtx;
+  private static Value newRef;
+  private static Value createRef;
+  private static Value getRef;
+  private static Value finalizeRef;
+
+  @BeforeClass
+  public static void initCtx() throws Exception {
+    ctx = ContextUtils.createDefaultContext();
+    ensoCtx = ContextUtils.leakContext(ctx);
+    var code =
+        """
+              import Standard.Base.Runtime.Managed_Resource.Managed_Resource
+
+              new_ref obj =
+                Managed_Resource.register obj (_->0)
+
+              create_ref obj system_resource =
+                Managed_Resource.register obj (_->0) system_resource
+
+              get_ref ref = ref.with it->
+                it
+              finalize_ref ref = ref.finalize
+              """;
+    var src = Source.newBuilder("enso", code, "gc.enso").build();
+    var gcEnso = ctx.eval(src);
+    newRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "new_ref");
+    createRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "create_ref");
+    getRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "get_ref");
+    finalizeRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "finalize_ref");
+  }
+
+  @AfterClass
+  public static void closeCtx() throws Exception {
+    ctx.close();
+    ctx = null;
+  }
+
+  @Test
+  public void regularReference() throws Exception {
+    var obj = new Object();
+    var ref = newRef.execute(obj);
+
+    assertFalse("Value returned", ref.isNull());
+    assertEquals(
+        "Standard.Base.Runtime.Managed_Resource.Managed_Resource",
+        ref.getMetaObject().getMetaQualifiedName());
+
+    var weakRef = new WeakReference<>(obj);
+    obj = null;
+
+    assertEquals("We get the object", weakRef.get(), getRef.execute(ref).asHostObject());
+
+    assertGC("Weak wasn't released", false, weakRef);
+    assertFalse("Value was not GCed", getRef.execute(ref).isNull());
+    assertEquals("We get the object", weakRef.get(), getRef.execute(ref).asHostObject());
+
+    ensoCtx.getResourceManager().scheduleFinalization();
+    assertEquals(
+        "scheduleFinalization has no effect on regular reference",
+        weakRef.get(),
+        getRef.execute(ref).asHostObject());
+  }
+
+  @Test
+  public void explicitlyReclaimableReference() throws Exception {
+    var obj = new Object();
+    var ref = createRef.execute(obj, true);
+
+    assertFalse("Value returned", ref.isNull());
+    assertEquals(
+        "Standard.Base.Runtime.Managed_Resource.Managed_Resource",
+        ref.getMetaObject().getMetaQualifiedName());
+    assertEquals("We get the object", obj, getRef.execute(ref).asHostObject());
+
+    ensoCtx.getResourceManager().scheduleFinalization();
+
+    assertTrue("Value was GCed", getRef.execute(ref).isNull());
+  }
+
+  private static void assertGC(String msg, boolean expectGC, Reference<?> ref) {
+    for (var i = 1; i < Integer.MAX_VALUE / 2; i *= 2) {
+      if (ref.get() == null) {
+        break;
+      }
+      System.gc();
+    }
+    var obj = ref.get();
+    if (expectGC) {
+      assertNull(msg + " ref still alive", obj);
+    } else {
+      assertNotNull(msg + " ref has been cleaned", obj);
+    }
+  }
+}

engine/runtime-integration-tests/src/test/java/org/enso/interpreter/runtime/RefTest.java

@@ -0,0 +1,93 @@
+package org.enso.interpreter.runtime;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+
+import java.lang.ref.Reference;
+import java.lang.ref.WeakReference;
+import org.enso.common.MethodNames;
+import org.enso.test.utils.ContextUtils;
+import org.graalvm.polyglot.Context;
+import org.graalvm.polyglot.Source;
+import org.graalvm.polyglot.Value;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class RefTest {
+  private static Context ctx;
+  private static EnsoContext ensoCtx;
+  private static Value newRef;
+  private static Value createRef;
+  private static Value getRef;
+
+  @BeforeClass
+  public static void initCtx() throws Exception {
+    ctx = ContextUtils.createDefaultContext();
+    ensoCtx = ContextUtils.leakContext(ctx);
+    var code =
+        """
+              import Standard.Base.Runtime.Ref.Ref
+
+              new_ref obj =
+                Ref.new obj
+
+              create_ref obj allow_gc =
+                Ref.new obj allow_gc
+
+              get_ref ref = ref.get
+              """;
+    var src = Source.newBuilder("enso", code, "gc.enso").build();
+    var gcEnso = ctx.eval(src);
+    newRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "new_ref");
+    createRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "create_ref");
+    getRef = gcEnso.invokeMember(MethodNames.Module.EVAL_EXPRESSION, "get_ref");
+  }
+
+  @AfterClass
+  public static void closeCtx() throws Exception {
+    ctx.close();
+    ctx = null;
+  }
+
+  @Test
+  public void regularReference() throws Exception {
+    var obj = new Object();
+    var ref = newRef.execute(obj);
+
+    assertFalse("Value returned", ref.isNull());
+    assertEquals("Standard.Base.Runtime.Ref.Ref", ref.getMetaObject().getMetaQualifiedName());
+
+    var weakRef = new WeakReference<>(obj);
+    obj = null;
+
+    assertEquals("We get the object", weakRef.get(), getRef.execute(ref).asHostObject());
+
+    assertGC("Weak wasn't released", false, weakRef);
+    assertFalse("Value was not GCed", getRef.execute(ref).isNull());
+    assertEquals("We get the object", weakRef.get(), getRef.execute(ref).asHostObject());
+
+    //    ensoCtx.getReferencesManager().releaseAll();
+    assertEquals(
+        "releaseAll has no effect on regular reference",
+        weakRef.get(),
+        getRef.execute(ref).asHostObject());
+  }
+
+  private static void assertGC(String msg, boolean expectGC, Reference<?> ref) {
+    for (var i = 1; i < Integer.MAX_VALUE / 2; i *= 2) {
+      if (ref.get() == null) {
+        break;
+      }
+      System.gc();
+    }
+    var obj = ref.get();
+    if (expectGC) {
+      assertNull(msg + " ref still alive", obj);
+    } else {
+      assertNotNull(msg + " ref has been cleaned", obj);
+    }
+  }
+}

engine/runtime/src/main/java/org/enso/interpreter/node/expression/builtin/resource/WithNode.java

@@ -1,23 +1,22 @@
 package org.enso.interpreter.node.expression.builtin.resource;
 
-import com.oracle.truffle.api.dsl.Specialization;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.nodes.Node;
 import org.enso.interpreter.dsl.BuiltinMethod;
 import org.enso.interpreter.node.callable.InvokeCallableNode;
 import org.enso.interpreter.runtime.EnsoContext;
-import org.enso.interpreter.runtime.ResourceManager;
 import org.enso.interpreter.runtime.callable.argument.CallArgumentInfo;
 import org.enso.interpreter.runtime.data.ManagedResource;
 import org.enso.interpreter.runtime.state.State;
 
 @BuiltinMethod(
     type = "Managed_Resource",
-    name = "with",
+    name = "with_builtin",
     description =
         "Applies the passed action to the underlying resource managed by the passed"
             + " Managed_Resource object.")
-public abstract class WithNode extends Node {
+public final class WithNode extends Node {
+  private WithNode() {}
 
   private @Child InvokeCallableNode invokeCallableNode =
       InvokeCallableNode.build(
@@ -26,19 +25,22 @@ public abstract class WithNode extends Node {
           InvokeCallableNode.ArgumentsExecutionMode.PRE_EXECUTED);
 
   static WithNode build() {
-    return WithNodeGen.create();
+    return new WithNode();
   }
 
-  abstract Object execute(State state, VirtualFrame frame, Object self, Object action);
-
-  @Specialization
-  Object doWith(State state, VirtualFrame frame, ManagedResource self, Object action) {
-    ResourceManager resourceManager = EnsoContext.get(this).getResourceManager();
-    resourceManager.park(self);
-    try {
-      return invokeCallableNode.execute(action, frame, state, new Object[] {self.getResource()});
-    } finally {
-      resourceManager.unpark(self);
+  Object execute(
+      State state, VirtualFrame frame, ManagedResource mr, Object action, Object onMissing) {
+    var ctx = EnsoContext.get(this);
+    var resourceManager = ctx.getResourceManager();
+    if (mr.getPhantomReference().refersTo(mr)) {
+      resourceManager.park(mr);
+      try {
+        return invokeCallableNode.execute(action, frame, state, new Object[] {mr.getResource()});
+      } finally {
+        resourceManager.unpark(mr);
+      }
+    } else {
+      return onMissing;
     }
   }
 }