Thread termination note in isolate tear down

Author: vjovanov

espresso/src/com.oracle.truffle.espresso.mokapot/include/graal_isolate_dynamic.h

@@ -127,6 +127,12 @@ typedef int (*graal_detach_thread_fn_t)(graal_isolatethread_t* thread);
  * waiting for any attached threads to detach from it, then discards its objects,
  * threads, and any other state or context that is associated with it.
  * Returns 0 on success, or a non-zero value on failure.
+ * 
+ * If this call blocks indefinitely, this means there are still Java-application threads running.
+ * To prevent indefinite blocking, these threads must be cooperatively shut down within Java before invoking this call.
+ * To fix this use the option '-R:TearDownWarningSeconds=<secs>' at image build time to detect the threads that are still running.
+ * This will print the stack traces of all threads that have not been cooperatively terminated.
+ * Those threads need to be terminated from Java before calling tear_down_isolate.
  */
 typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread);
 
@@ -141,6 +147,12 @@ typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread
  * Java code at the time when this function is called or at any point in the future
  * or this will cause entirely undefined (and likely fatal) behavior.
  * Returns 0 on success, or a non-zero value on (non-fatal) failure.
+ * 
+ * If this call blocks indefinitely, this means there are still Java-application threads running.
+ * To prevent indefinite blocking, these threads must be cooperatively shut down within Java before invoking this call.
+ * To fix this use the option '-R:TearDownWarningSeconds=<secs>' at image build time to detect the threads that are still running.
+ * This will print the stack traces of all threads that have not been cooperatively terminated.
+ * Those threads need to be terminated from Java before calling tear_down_isolate.
  */
 typedef int (*graal_detach_all_threads_and_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread);
 

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java

@@ -24,6 +24,8 @@
  */
 package com.oracle.svm.core;
 
+import static com.oracle.svm.core.SubstrateOptions.DeprecatedOptions.TearDownFailureNanos;
+import static com.oracle.svm.core.SubstrateOptions.DeprecatedOptions.TearDownWarningNanos;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.Immutable;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.IsolateCreationOnly;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.RelevantForCompilationIsolates;
@@ -63,6 +65,7 @@
 import com.oracle.svm.core.option.RuntimeOptionKey;
 import com.oracle.svm.core.option.SubstrateOptionsParser;
 import com.oracle.svm.core.thread.VMOperationControl;
+import com.oracle.svm.core.util.TimeUtils;
 import com.oracle.svm.core.util.UserError;
 import com.oracle.svm.util.LogUtils;
 import com.oracle.svm.util.ModuleSupport;
@@ -576,6 +579,13 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, Boolean o
                 }
             }
         };
+
+        @Option(help = "The number of nanoseconds before and between which tearing down an isolate gives a warning message. 0 implies no warning.", deprecated = true, deprecationMessage = "Use TearDownWarningSeconds instead")//
+        public static final RuntimeOptionKey<Long> TearDownWarningNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
+
+        @Option(help = "The number of nanoseconds before tearing down an isolate gives a failure message. 0 implies no message.", deprecated = true, deprecationMessage = "Use TearDownFailureSeconds instead")//
+        public static final RuntimeOptionKey<Long> TearDownFailureNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
+
     }
 
     @Option(help = "Enable detection and runtime container configuration support.")//
@@ -818,18 +828,35 @@ private static void validateZapNativeMemory(HostedOptionKey<Boolean> optionKey)
      * Isolate tear down options.
      */
 
-    @Option(help = "The number of nanoseconds before and between which tearing down an isolate gives a warning message.  0 implies no warning.")//
-    public static final RuntimeOptionKey<Long> TearDownWarningNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
+    @Option(help = "The number of seconds before and between which tearing down an isolate gives a warning message. 0 implies no warning.")//
+    public static final RuntimeOptionKey<Long> TearDownWarningSeconds = new RuntimeOptionKey<>(0L, key -> validateTearDownTimeoutOptions(), RelevantForCompilationIsolates);
 
-    @Option(help = "The number of nanoseconds before tearing down an isolate gives a failure message.  0 implies no message.")//
-    public static final RuntimeOptionKey<Long> TearDownFailureNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
+    @Option(help = "The number of seconds before tearing down an isolate gives a failure message. 0 implies no message.")//
+    public static final RuntimeOptionKey<Long> TearDownFailureSeconds = new RuntimeOptionKey<>(0L, key -> validateTearDownTimeoutOptions(), RelevantForCompilationIsolates);
+
+    private static void validateTearDownTimeoutOptions() {
+        if (TearDownWarningSeconds.hasBeenSet() && TearDownWarningNanos.hasBeenSet()) {
+            throw new IllegalArgumentException("Can't set both TearDownWarningSeconds and TearDownWarningNanos at the same time. Use TearDownWarningSeconds.");
+        }
+        if (TearDownFailureSeconds.hasBeenSet() && TearDownFailureNanos.hasBeenSet()) {
+            throw new IllegalArgumentException("Can't set both TearDownFailureSeconds and TearDownFailureNanos at the same time. Use TearDownFailureSeconds.");
+        }
+    }
 
     public static long getTearDownWarningNanos() {
-        return TearDownWarningNanos.getValue();
+        validateTearDownTimeoutOptions();
+        if (TearDownWarningNanos.hasBeenSet()) {
+            return TearDownWarningNanos.getValue();
+        }
+        return TearDownWarningSeconds.getValue() * TimeUtils.nanosPerSecond;
     }
 
     public static long getTearDownFailureNanos() {
-        return TearDownFailureNanos.getValue();
+        validateTearDownTimeoutOptions();
+        if (TearDownFailureNanos.hasBeenSet()) {
+            return TearDownFailureNanos.getValue();
+        }
+        return TearDownFailureSeconds.getValue() * TimeUtils.nanosPerSecond;
     }
 
     @Option(help = "Define the maximum number of stores for which the loop that zeroes out objects is unrolled.")//

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointNativeFunctions.java

@@ -26,7 +26,6 @@
 
 import java.util.function.Function;
 
-import jdk.graal.compiler.word.Word;
 import org.graalvm.nativeimage.CurrentIsolate;
 import org.graalvm.nativeimage.Isolate;
 import org.graalvm.nativeimage.IsolateThread;
@@ -41,6 +40,8 @@
 import com.oracle.svm.core.c.function.CEntryPointOptions.NoPrologue;
 import com.oracle.svm.core.thread.VMThreads;
 
+import jdk.graal.compiler.word.Word;
+
 @CHeader(value = GraalIsolateHeader.class)
 public final class CEntryPointNativeFunctions {
 
@@ -158,12 +159,26 @@ public static int detachThread(IsolateThread thread) {
         return CEntryPointActions.leaveDetachThread();
     }
 
+    static final String THREAD_TERMINATION_NOTE = """
+                    
+                    If this call blocks indefinitely, this means there are still Java threads running
+                    that do not terminate after receiving a Thread.interrupt() event. To prevent indefinite blocking,
+                    these threads should be cooperatively terminated within Java before invoking this call.
+                    To diagnose such issues, use the option '-R:TearDownWarningSeconds=<secs>' at image build time
+                    to detect the threads that are still running. This will print the stack traces of all threads that block tear-down.
+                    To resolve blocking issues, utilize any available method to terminate the offending threads. This may include
+                    calling shutdown API functions, adjusting the application configuration, or leveraging reflection.
+                    """;
+
     @Uninterruptible(reason = UNINTERRUPTIBLE_REASON)
-    @CEntryPoint(name = "tear_down_isolate", documentation = {
-                    "Tears down the isolate of the passed (and still attached) isolate thread,",
-                    "waiting for any attached threads to detach from it, then discards its objects,",
-                    "threads, and any other state or context that is associated with it.",
-                    "Returns 0 on success, or a non-zero value on failure."})
+    @CEntryPoint(name = "tear_down_isolate", documentation = {"""
+                    Tears down the isolate of the passed (and still attached) isolate thread,
+                    waiting for any attached threads to detach from it, then discards its objects,
+                    threads, and any other state or context that is associated with it.
+                    Returns 0 on success, or a non-zero value on failure.
+                    """,
+                    THREAD_TERMINATION_NOTE,
+    })
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static int tearDownIsolate(IsolateThread isolateThread) {
         int result = CEntryPointActions.enter(isolateThread);
@@ -174,17 +189,20 @@ public static int tearDownIsolate(IsolateThread isolateThread) {
     }
 
     @Uninterruptible(reason = UNINTERRUPTIBLE_REASON)
-    @CEntryPoint(name = "detach_all_threads_and_tear_down_isolate", documentation = {
-                    "In the isolate of the passed isolate thread, detach all those threads that were",
-                    "externally started (not within Java, which includes the \"main thread\") and were",
-                    "attached to the isolate afterwards. Afterwards, all threads that were started",
-                    "within Java undergo a regular shutdown process, followed by the tear-down of the",
-                    "entire isolate, which detaches the current thread and discards the objects,",
-                    "threads, and any other state or context associated with the isolate.",
-                    "None of the manually attached threads targeted by this function may be executing",
-                    "Java code at the time when this function is called or at any point in the future",
-                    "or this will cause entirely undefined (and likely fatal) behavior.",
-                    "Returns 0 on success, or a non-zero value on (non-fatal) failure."})
+    @CEntryPoint(name = "detach_all_threads_and_tear_down_isolate", documentation = {"""
+                    In the isolate of the passed isolate thread, detach all those threads that were
+                    externally started (not within Java, which includes the "main thread") and were
+                    attached to the isolate afterwards. Afterwards, all threads that were started
+                    within Java undergo a regular shutdown process, followed by the tear-down of the
+                    entire isolate, which detaches the current thread and discards the objects,
+                    threads, and any other state or context associated with the isolate.
+                    None of the manually attached threads targeted by this function may be executing
+                    Java code at the time when this function is called or at any point in the future
+                    or this will cause entirely undefined (and likely fatal) behavior.
+                    Returns 0 on success, or a non-zero value on (non-fatal) failure.
+                    """,
+                    THREAD_TERMINATION_NOTE,
+    })
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static int detachAllThreadsAndTearDownIsolate(IsolateThread isolateThread) {
         int result = CEntryPointActions.enter(isolateThread);