[GR-54300] Improve GC based disposal of polyglot engine and context.

Author: tzezula

sdk/CHANGELOG.md

@@ -7,6 +7,7 @@ This changelog summarizes major changes between GraalVM SDK versions. The main f
 * GR-57681 Added the ability to use `Value#as(byte[].class)` to copy the contents of a guest language byte buffer (`Value#hasBufferElements()`) to a new byte array. The new functionality has precedence over accessing the guest object as array (`Value#hasArrayElements()`) if both ways are available. 
 * GR-57817 Starting with JDK 24 users now need to configure native access privileges to the java executable in order to avoid warnings from being printed by the JDK.
 For usages of the module-path pass the `--enable-native-access=org.graalvm.truffle` option and for class-path usages pass the `--enable-native-access=ALL-UNNAMED` option to resolve the new warning. Note that Truffle automatically forwards the native access capability to all loaded languages and tools, therefore no further configuration is required. If the native access is denied by the user with `--illegal-native-access=deny` then loading the optimizing runtime will fail and the fallback runtime will be used. More information can be found in the integrity-by-default [JEP-472](https://openjdk.org/jeps/472).
+* GR-54300 `Context` and `Engine` is now automatically closed when no longer strongly referenced. A reachable `Value` or `PolyglotException` will keep the associated `Context` reachable. Additionally, the `Context` remains reachable when explicitly entered or if there is an active polyglot thread within it. The `Engine` remains reachable when there is a strongly reachable `Language`, `Instrument`, or `Context` instance. However, it is still recommended not to rely on garbage collection for closing. Instead, use the try-with-resources pattern for explicit context and engine management. For more information, refer to the [Automatic Close on GC documentation](https://github.com/oracle/graal/blob/master/truffle/docs/CloseOnGc.md).
 
 ## Version 24.1.0
 * GR-51177 Enable random offsets of runtime compiled function entry points for the UNTRUSTED polyglot sandbox policy.

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Context.java

@@ -42,6 +42,7 @@
 
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.lang.ref.Reference;
 import java.nio.file.Path;
 import java.time.Duration;
 import java.time.Instant;
@@ -102,9 +103,10 @@
  * {@link #initialize(String) initialized}.
  * <li>Then, we assert the result value by converting the result value as primitive <code>int</code>
  * .
- * <li>Finally, if the context is no longer needed, it is necessary to close it to ensure that all
- * resources are freed. Contexts are also {@link AutoCloseable} for use with the Java
- * {@code try-with-resources} statement.
+ * <li>Finally, when a context is no longer needed, it is recommended to explicitly close it to
+ * ensure timely release of resources. While contexts are automatically closed when no longer
+ * strongly reachable, explicit closure is still preferred. Contexts are also {@link AutoCloseable},
+ * allowing them to be used with the Java {@code try-with-resources} statement.
  * </ul>
  *
  * <h3>Configuration</h3>
@@ -337,29 +339,40 @@ public final class Context implements AutoCloseable {
     final AbstractContextDispatch dispatch;
     final Object receiver;
     final Context currentAPI;
+    final Context parent;
+    /**
+     * Strong reference to the creator {@link Context} to prevent it from being garbage collected
+     * and closed while API {@link Context} is still reachable.
+     */
+    final Context creatorContext;
     final Engine engine;
 
     @SuppressWarnings("unchecked")
-    <T> Context(AbstractContextDispatch dispatch, T receiver, Engine engine) {
+    <T> Context(AbstractContextDispatch dispatch, T receiver, Context parentContext, Engine engine) {
         this.dispatch = dispatch;
         this.receiver = receiver;
         this.engine = engine;
         this.currentAPI = new Context(this);
-        dispatch.setAPI(receiver, this);
+        this.parent = parentContext;
+        this.creatorContext = this;
     }
 
     private Context() {
         this.dispatch = null;
         this.receiver = null;
         this.engine = null;
         this.currentAPI = null;
+        this.parent = null;
+        this.creatorContext = null;
     }
 
     private <T> Context(Context creatorAPI) {
         this.dispatch = creatorAPI.dispatch;
         this.receiver = creatorAPI.receiver;
         this.engine = creatorAPI.engine.currentAPI;
         this.currentAPI = null;
+        this.parent = creatorAPI.parent != null ? creatorAPI.parent.currentAPI : null;
+        this.creatorContext = creatorAPI;
     }
 
     /**
@@ -399,7 +412,11 @@ public Engine getEngine() {
      * @since 19.0
      */
     public Value eval(Source source) {
-        return (Value) dispatch.eval(receiver, source.getLanguage(), source);
+        try {
+            return (Value) dispatch.eval(receiver, source.getLanguage(), source);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -425,7 +442,11 @@ public Value eval(Source source) {
      * @since 19.0
      */
     public Value eval(String languageId, CharSequence source) {
-        return eval(Source.create(languageId, source));
+        try {
+            return eval(Source.create(languageId, source));
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -480,7 +501,11 @@ public Value eval(String languageId, CharSequence source) {
      * @since 20.2
      */
     public Value parse(Source source) throws PolyglotException {
-        return (Value) dispatch.parse(receiver, source.getLanguage(), source);
+        try {
+            return (Value) dispatch.parse(receiver, source.getLanguage(), source);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -523,7 +548,11 @@ public Value parse(Source source) throws PolyglotException {
      * @since 20.2
      */
     public Value parse(String languageId, CharSequence source) {
-        return parse(Source.create(languageId, source));
+        try {
+            return parse(Source.create(languageId, source));
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -543,7 +572,11 @@ public Value parse(String languageId, CharSequence source) {
      * @since 19.0
      */
     public Value getPolyglotBindings() {
-        return (Value) dispatch.getPolyglotBindings(receiver);
+        try {
+            return (Value) dispatch.getPolyglotBindings(receiver);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -560,7 +593,11 @@ public Value getPolyglotBindings() {
      * @since 19.0
      */
     public Value getBindings(String languageId) {
-        return (Value) dispatch.getBindings(receiver, languageId);
+        try {
+            return (Value) dispatch.getBindings(receiver, languageId);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -576,7 +613,11 @@ public Value getBindings(String languageId) {
      * @since 19.0
      */
     public boolean initialize(String languageId) {
-        return dispatch.initializeLanguage(receiver, languageId);
+        try {
+            return dispatch.initializeLanguage(receiver, languageId);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -586,6 +627,7 @@ public boolean initialize(String languageId) {
      */
     public void resetLimits() {
         dispatch.resetLimits(receiver);
+        Reference.reachabilityFence(creatorContext);
     }
 
     /**
@@ -735,7 +777,11 @@ public void resetLimits() {
      * @since 19.0
      */
     public Value asValue(Object hostValue) {
-        return (Value) dispatch.asValue(receiver, hostValue);
+        try {
+            return (Value) dispatch.asValue(receiver, hostValue);
+        } finally {
+            Reference.reachabilityFence(creatorContext);
+        }
     }
 
     /**
@@ -754,6 +800,7 @@ public Value asValue(Object hostValue) {
     public void enter() {
         checkCreatorAccess("entered");
         dispatch.explicitEnter(receiver);
+        Reference.reachabilityFence(creatorContext);
     }
 
     /**
@@ -832,6 +879,7 @@ private void checkCreatorAccess(String operation) {
     public void close(boolean cancelIfExecuting) {
         checkCreatorAccess("closed");
         dispatch.close(receiver, cancelIfExecuting);
+        Reference.reachabilityFence(creatorContext);
     }
 
     /**
@@ -883,6 +931,7 @@ public void interrupt(Duration timeout) throws TimeoutException {
         if (!dispatch.interrupt(receiver, timeout)) {
             throw new TimeoutException("Interrupt timed out.");
         }
+        Reference.reachabilityFence(creatorContext);
     }
 
     /**
@@ -929,6 +978,7 @@ public void interrupt(Duration timeout) throws TimeoutException {
      */
     public void safepoint() {
         dispatch.safepoint(receiver);
+        Reference.reachabilityFence(creatorContext);
     }
 
     /**
@@ -1934,11 +1984,11 @@ public Context build() {
             }
             Object logHandler = customLogHandler != null ? Engine.getImpl().newLogHandler(customLogHandler) : null;
             String tmpDir = Engine.getImpl().getIO().hasHostFileAccess(useIOAccess) ? System.getProperty("java.io.tmpdir") : null;
-            ctx = (Context) engine.dispatch.createContext(engine.receiver, useSandboxPolicy, contextOut, contextErr, contextIn, hostClassLookupEnabled,
+            ctx = engine.dispatch.createContext(engine.receiver, engine, useSandboxPolicy, contextOut, contextErr, contextIn, hostClassLookupEnabled,
                             hostAccess, polyglotAccess, nativeAccess, createThread, hostClassLoading, innerContextOptions,
                             experimentalOptions, localHostLookupFilter, contextOptions, arguments == null ? Collections.emptyMap() : arguments,
                             permittedLanguages, useIOAccess, logHandler, createProcess, processHandler, useEnvironmentAccess, environment, zone, limits,
-                            localCurrentWorkingDirectory, tmpDir, hostClassLoader, allowValueSharing, useSystemExit);
+                            localCurrentWorkingDirectory, tmpDir, hostClassLoader, allowValueSharing, useSystemExit, true);
             return ctx;
         }