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,30 @@ 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, 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, RelevantForCompilationIsolates);
 
     public static long getTearDownWarningNanos() {
-        return TearDownWarningNanos.getValue();
+        if (TearDownWarningSeconds.hasBeenSet() && TearDownWarningNanos.hasBeenSet()) {
+            throw new IllegalArgumentException("Can't set both TearDownWarningSeconds and TearDownWarningNanos at the same time. Use TearDownWarningSeconds.");
+        }
+        if (TearDownWarningNanos.hasBeenSet()) {
+            return TearDownWarningNanos.getValue();
+        }
+        return TearDownWarningSeconds.getValue() * TimeUtils.nanosPerSecond;
     }
 
     public static long getTearDownFailureNanos() {
-        return TearDownFailureNanos.getValue();
+        if (TearDownFailureSeconds.hasBeenSet() && TearDownFailureNanos.hasBeenSet()) {
+            throw new IllegalArgumentException("Can't set both TearDownFailureSeconds and TearDownFailureNanos at the same time. Use TearDownFailureSeconds.");
+        }
+        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,25 @@ public static int detachThread(IsolateThread thread) {
         return CEntryPointActions.leaveDetachThread();
     }
 
+    static final String THREAD_TERMINATION_NOTE_1 = "If this call blocks indefinitely, this means there are still Java-application threads running.";
+    static final String THREAD_TERMINATION_NOTE_2 = "To prevent indefinite blocking, these threads must be cooperatively shut down within Java before invoking this call.";
+    static final String THREAD_TERMINATION_NOTE_3 = "To fix this use the option '-R:TearDownWarningSeconds=<secs>' at image build time to detect the threads that are still running.";
+    static final String THREAD_TERMINATION_NOTE_4 = "This will print the stack traces of all threads that have not been cooperatively terminated.";
+    static final String THREAD_TERMINATION_NOTE_5 = "Those threads need to be terminated from Java before calling tear_down_isolate.";
+
     @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."})
+                    "Returns 0 on success, or a non-zero value on failure.",
+                    "",
+                    THREAD_TERMINATION_NOTE_1,
+                    THREAD_TERMINATION_NOTE_2,
+                    THREAD_TERMINATION_NOTE_3,
+                    THREAD_TERMINATION_NOTE_4,
+                    THREAD_TERMINATION_NOTE_5
+    })
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static int tearDownIsolate(IsolateThread isolateThread) {
         int result = CEntryPointActions.enter(isolateThread);
@@ -184,7 +198,13 @@ public static int tearDownIsolate(IsolateThread isolateThread) {
                     "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."})
+                    "Returns 0 on success, or a non-zero value on (non-fatal) failure.",
+                    "",
+                    THREAD_TERMINATION_NOTE_1,
+                    THREAD_TERMINATION_NOTE_2,
+                    THREAD_TERMINATION_NOTE_3,
+                    THREAD_TERMINATION_NOTE_4,
+                    THREAD_TERMINATION_NOTE_5})
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static int detachAllThreadsAndTearDownIsolate(IsolateThread isolateThread) {
         int result = CEntryPointActions.enter(isolateThread);