Thread termination note in isolate tear-down

Introduced -R:TearDownWarningSeconds
Depracated -R:TearDownWarningNanos and -R:TearDownFailureSeconds

Author: vjovanov

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

@@ -127,6 +127,11 @@ 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 threads running which do not terminate after receiving the Thread.interrupt() event.
+ * To prevent indefinite blocking, these threads should be cooperatively shut down within Java before invoking this call.
+ * To diagnose such issues, use the option '-R:TearDownWarningSeconds=<secs>' to detect the threads that are still running.
+ * This will print the stack traces of all threads that block tear-down.
  */
 typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread);
 
@@ -141,6 +146,11 @@ 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 threads running which do not terminate after receiving the Thread.interrupt() event.
+ * To prevent indefinite blocking, these threads should be cooperatively shut down within Java before invoking this call.
+ * To diagnose such issues, use the option '-R:TearDownWarningSeconds=<secs>' to detect the threads that are still running.
+ * This will print the stack traces of all threads that block tear-down.
  */
 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,7 @@
  */
 package com.oracle.svm.core;
 
+import static com.oracle.svm.core.SubstrateOptions.DeprecatedOptions.TearDownFailureNanos;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.Immutable;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.RegisterForIsolateArgumentParser;
 import static com.oracle.svm.core.option.RuntimeOptionKey.RuntimeOptionKeyFlag.RelevantForCompilationIsolates;
@@ -72,6 +73,7 @@
 import com.oracle.svm.core.option.SubstrateOptionsParser;
 import com.oracle.svm.core.pltgot.PLTGOTConfiguration;
 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.core.util.VMError;
 import com.oracle.svm.util.LogUtils;
@@ -608,6 +610,18 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, Boolean o
                 }
             }
         };
+
+        public static final String TEAR_DOWN_WARNING_NANOS_ERROR = "Can't set both TearDownWarningSeconds and TearDownWarningNanos at the same time. Use TearDownWarningSeconds.";
+        @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 -XX:TearDownWarningSeconds=<secs> instead")//
+        public static final RuntimeOptionKey<Long> TearDownWarningNanos = new RuntimeOptionKey<>(0L,
+                        (key) -> UserError.guarantee(!(key.hasBeenSet() && TearDownWarningSeconds.hasBeenSet()), TEAR_DOWN_WARNING_NANOS_ERROR),
+                        RelevantForCompilationIsolates);
+
+        @Option(help = "The number of nanoseconds before tearing down an isolate gives a failure message and returns from a tear-down call. 0 implies no message.", //
+                        deprecated = true, deprecationMessage = "This call leaks resources. Instead, terminate java threads cooperatively, or use System#exit")//
+        public static final RuntimeOptionKey<Long> TearDownFailureNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
+
     }
 
     @LayerVerifiedOption(kind = Kind.Changed, severity = Severity.Error)//
@@ -866,11 +880,17 @@ private static void validateZapNativeMemory(HostedOptionKey<Boolean> optionKey)
     public static final RuntimeOptionKey<Long> TearDownWarningNanos = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
 
     @LayerVerifiedOption(kind = Kind.Changed, severity = Severity.Error)//
-    @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 and between which tearing down an isolate gives a warning message. 0 implies no warning.")//
+    public static final RuntimeOptionKey<Long> TearDownWarningSeconds = new RuntimeOptionKey<>(0L, RelevantForCompilationIsolates);
 
     public static long getTearDownWarningNanos() {
-        return TearDownWarningNanos.getValue();
+        if (TearDownWarningSeconds.hasBeenSet() && TearDownWarningNanos.hasBeenSet()) {
+            throw new IllegalArgumentException(DeprecatedOptions.TEAR_DOWN_WARNING_NANOS_ERROR);
+        }
+        if (TearDownWarningNanos.hasBeenSet()) {
+            return TearDownWarningNanos.getValue();
+        }
+        return TearDownWarningSeconds.getValue() * TimeUtils.nanosPerSecond;
     }
 
     public static long getTearDownFailureNanos() {

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,22 @@ 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 which do not terminate after receiving the Thread.interrupt() event.
+                    To prevent indefinite blocking, these threads should be cooperatively shut down within Java before invoking this call.
+                    To diagnose such issues, use the option '-R:TearDownWarningSeconds=<secs>' to detect the threads that are still running.
+                    This will print the stack traces of all threads that block tear-down.
+                    """;
+
     @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 +185,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);