Allow system controlled Managed_Resource

Author: Jaroslav Tulach

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
@@ -78,3 +87,5 @@ 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"

engine/runtime/src/main/java/org/enso/interpreter/runtime/ResourceManager.java

@@ -112,22 +112,40 @@ public void take(ManagedResource resource) {
     removeFromItems(resource.getPhantomReference());
   }
 
+  /**
+   * Registers a new (non-system controlled) resource to the system. Calls {@link
+   * #register(java.lang.Object, java.lang.Object, boolean)} with {@code false} as last argument.
+   *
+   * @param object the underlying resource
+   * @param function the finalizer action to call on the underlying resource
+   * @return a wrapper object, containing the resource and serving as a reachability probe
+   */
+  @CompilerDirectives.TruffleBoundary
+  public ManagedResource register(Object object, Object function) {
+    return register(object, function, false);
+  }
+
   /**
    * Registers a new resource to the system. {@code function} will be called on {@code object} when
    * the value returned by this method becomes unreachable.
    *
    * @param object the underlying resource
    * @param function the finalizer action to call on the underlying resource
+   * @param systemResource resource is subject to finalization when {@link #scheduleFinalization} is
+   *     called
    * @return a wrapper object, containing the resource and serving as a reachability probe
    */
   @CompilerDirectives.TruffleBoundary
-  public synchronized ManagedResource register(Object object, Object function) {
+  public synchronized ManagedResource register(
+      Object object, Object function, boolean systemResource) {
     if (CLOSED == processor) {
       throw EnsoContext.get(null)
           .raiseAssertionPanic(
               null, "Can't register new resources after resource manager is closed.", null);
     }
-    var resource = new ManagedResource(object, r -> new Item(r, object, function, referenceQueue));
+    var resource =
+        new ManagedResource(
+            object, r -> new Item(r, object, function, systemResource, referenceQueue));
     var ref = (Item) resource.getPhantomReference();
     addPendingItem(ref);
     return resource;
@@ -186,6 +204,21 @@ private synchronized void removeFromItems(PhantomReference<ManagedResource> it)
     }
   }
 
+  /**
+   * Explicitly schedules all the <em>system references</em> registered with the manager for
+   * finalization.
+   *
+   * @see #register
+   */
+  @CompilerDirectives.TruffleBoundary
+  public final synchronized void scheduleFinalization() {
+    for (var item : pendingItems) {
+      if (item.systemResource) {
+        item.enqueue();
+      }
+    }
+  }
+
   /**
    * Awaits next item in the queue, if any.
    *
@@ -360,6 +393,7 @@ Collection<Item> awaitShutdown() {
 
   /** A storage representation of a finalizable object handled by this system. */
   private static final class Item extends PhantomReference<ManagedResource> {
+    private final boolean systemResource;
     private final Object underlying;
     private final Object finalizer;
 
@@ -393,10 +427,12 @@ private Item(
         ManagedResource referent,
         Object underlying,
         Object finalizer,
+        boolean systemResource,
         ReferenceQueue<ManagedResource> queue) {
       super(referent, queue);
       this.underlying = underlying;
       this.finalizer = finalizer;
+      this.systemResource = systemResource;
     }
 
     /**

engine/runtime/src/main/java/org/enso/interpreter/runtime/data/ManagedResource.java

@@ -73,8 +73,9 @@ public PhantomReference<ManagedResource> getPhantomReference() {
           "Makes an object into a managed resource, automatically finalized when the returned"
               + " object is garbage collected.")
   @Builtin.Specialize
-  public static ManagedResource register(EnsoContext context, Object resource, Function function) {
-    return context.getResourceManager().register(resource, function);
+  public static ManagedResource register_builtin(
+      EnsoContext context, Object resource, Function function, boolean systemCanFinalize) {
+    return context.getResourceManager().register(resource, function, systemCanFinalize);
   }
 
   @Builtin.Method(