Skip to content

[GR-63694] Thread termination note in isolate tear down. #10965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 6, 2025
Merged

[GR-63694] Thread termination note in isolate tear down. #10965

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions espresso/src/com.oracle.truffle.espresso.mokapot/include/graal_isolate_dynamic.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,14 @@ 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);

Expand All @@ -141,6 +149,14 @@ 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);

Expand Down
30 changes: 23 additions & 7 deletions substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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)//
Expand Down Expand Up @@ -862,15 +876,17 @@ private static void validateZapNativeMemory(HostedOptionKey<Boolean> optionKey)
*/

@LayerVerifiedOption(kind = Kind.Changed, severity = Severity.Error)//
@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);

@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() && DeprecatedOptions.TearDownWarningNanos.hasBeenSet()) {
throw new IllegalArgumentException(DeprecatedOptions.TEAR_DOWN_WARNING_NANOS_ERROR);
}
if (DeprecatedOptions.TearDownWarningNanos.hasBeenSet()) {
return DeprecatedOptions.TearDownWarningNanos.getValue();
}
return TearDownWarningSeconds.getValue() * TimeUtils.nanosPerSecond;
}

public static long getTearDownFailureNanos() {
Expand Down
51 changes: 34 additions & 17 deletions ...rc/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointNativeFunctions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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 {

Expand Down Expand Up @@ -158,12 +159,25 @@ 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);
Expand All @@ -174,17 +188,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);
Expand Down