From 964a26ac1ecd53d1a9bedefb573812322edfb835 Mon Sep 17 00:00:00 2001
From: Tim Felgentreff <tim.felgentreff@oracle.com>
Date: Fri, 8 May 2026 00:07:20 +0200
Subject: [PATCH 1/4] Consider native weakref growth as well as GC minimum

---
 .../objects/cext/capi/CApiContext.java        | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
index 7dee2c1dee..9d826b4afa 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
@@ -609,7 +609,7 @@ private BackgroundGCTask(PythonContext context) {
             super("Python GC", LOGGER);
             this.ctx = new WeakReference<>(context);
             this.rssInterval = context.getOption(PythonOptions.BackgroundGCTaskInterval);
-            this.gcRSSThreshold = context.getOption(PythonOptions.BackgroundGCTaskThreshold) / (double) 100;
+            this.gcGrowthThreshold = context.getOption(PythonOptions.BackgroundGCTaskThreshold) / (double) 100;
             this.gcRSSMinimum = context.getOption(PythonOptions.BackgroundGCTaskMinimum);
         }
 
@@ -624,7 +624,7 @@ private BackgroundGCTask(PythonContext context) {
         // RSS monitor interval in ms
         final int rssInterval;
         /**
-         * RSS percentage increase between System.gc() calls. Low percentage will trigger
+         * Resources percentage increase between System.gc() calls. Low percentage will trigger
          * System.gc() more often which can cause unnecessary overhead.
          *
          * <ul>
@@ -636,7 +636,7 @@ private BackgroundGCTask(PythonContext context) {
          *
          * <pre>
          */
-        final double gcRSSThreshold;
+        final double gcGrowthThreshold;
 
         /**
          * RSS minimum memory (in megabytes) start calling System.gc(). Default is 4GB.
@@ -695,10 +695,6 @@ private void perform() {
                 return;
             }
 
-            if (rss < gcRSSMinimum) {
-                return;
-            }
-
             // skip GC if no new native weakrefs have been created.
             int currentWeakrefCount = context.handleContext.nativeLookup.size();
             if (currentWeakrefCount < this.previousWeakrefCount || this.previousWeakrefCount == -1) {
@@ -706,8 +702,13 @@ private void perform() {
                 return;
             }
 
-            double ratio = ((rss - this.previousRSS) / (double) this.previousRSS);
-            if (ratio >= gcRSSThreshold) {
+            double ratio = ((currentWeakrefCount - this.previousWeakrefCount) / (double) Math.max(1, this.previousWeakrefCount));
+            if (rss < gcRSSMinimum && ratio < gcGrowthThreshold) {
+                return;
+            }
+
+            ratio = ((rss - this.previousRSS) / (double) this.previousRSS);
+            if (ratio >= gcGrowthThreshold) {
                 this.previousWeakrefCount = currentWeakrefCount;
 
                 long start = System.nanoTime();
@@ -729,7 +730,7 @@ private void perform() {
                  * mappings (RssFile) and shmem memory (RssShmem). GC can only reduce RssAnon while
                  * RssFile is managed by the operating system which doesn't go down easily.
                  */
-                this.previousRSS += (long) (this.previousRSS * gcRSSThreshold);
+                this.previousRSS += (long) (this.previousRSS * gcGrowthThreshold);
             }
         }
     }

From fed2aeaf726a62525e1a3814e88f535441514dc0 Mon Sep 17 00:00:00 2001
From: Tim Felgentreff <tim.felgentreff@oracle.com>
Date: Fri, 8 May 2026 06:41:29 +0200
Subject: [PATCH 2/4] Constrain BackgroundGCTaskThreshold to valid percentage
 values.

---
 .../graal/python/runtime/PythonOptions.java       | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java
index fc8c4d05a5..912b41aa90 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java
@@ -381,8 +381,19 @@ public static void checkBytecodeDSLEnv() {
     @Option(category = OptionCategory.INTERNAL, usageSyntax = "<time>", help = "Specifies the interval (ms) for the background GC task to monitor the resident set size (RSS)") //
     public static final OptionKey<Integer> BackgroundGCTaskInterval = new OptionKey<>(1000);
 
-    @Option(category = OptionCategory.INTERNAL, usageSyntax = "<limit>", help = "The percentage increase in RSS memory between System.gc() calls. Low percentage will trigger System.gc() more often. (default: 30).") //
-    public static final OptionKey<Integer> BackgroundGCTaskThreshold = new OptionKey<>(30);
+    @Option(category = OptionCategory.INTERNAL, usageSyntax = "[1,100]", help = "The percentage increase in RSS memory between System.gc() calls. Low percentage will trigger System.gc() more often. (default: 30).") //
+    public static final OptionKey<Integer> BackgroundGCTaskThreshold = new OptionKey<>(30,
+                    new OptionType<>("BackgroundGCTaskThreshold", input -> {
+                        try {
+                            int value = Integer.parseInt(input);
+                            if (value >= 1 && value <= 100) {
+                                return value;
+                            }
+                        } catch (NumberFormatException e) {
+                            // fallthrough
+                        }
+                        throw new IllegalArgumentException("BackgroundGCTaskThreshold must be an integer in range [1, 100]");
+                    }));
 
     @Option(category = OptionCategory.INTERNAL, usageSyntax = "<megabytes>", help = "The minimum RSS memory (in megabytes) to start calling System.gc(). (default: 4 GB).") //
     public static final OptionKey<Integer> BackgroundGCTaskMinimum = new OptionKey<>(4096);

From abb7ed4e42a8a61360ca60cd29cf477ea8da96ef Mon Sep 17 00:00:00 2001
From: Tim Felgentreff <tim.felgentreff@oracle.com>
Date: Fri, 8 May 2026 00:11:31 +0200
Subject: [PATCH 3/4] Document native extension virtual thread limitation

---
 docs/user/Embedding-Native-Extensions.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/user/Embedding-Native-Extensions.md b/docs/user/Embedding-Native-Extensions.md
index eaa31c0cd3..c413e66c6f 100644
--- a/docs/user/Embedding-Native-Extensions.md
+++ b/docs/user/Embedding-Native-Extensions.md
@@ -13,6 +13,13 @@ The Context API allows you to set options such as `allowIO`, `allowHostAccess`,
 To use Python native extensions on GraalPy, the `allowNativeAccess` option must be set to `true`, but this opens the door to full native access.
 This means that while Python code may be denied access to the host file system, thread or subprocess creation, and more, the native extension is under no such restriction.
 
+## Java Virtual Threads
+
+Python native extensions are not compatible with Java virtual threads.
+Native extensions commonly use native thread-local state, including CPython and extension-runtime state that cannot track Java virtual-thread scheduling.
+If an embedded application may load or call native extensions, run that Python code on platform threads.
+For example, server applications that use virtual threads for request handling should dispatch GraalPy calls that may use native extensions to a platform-thread executor.
+
 ## Memory Management
 
 Python C extensions, like the CPython reference implementation, use reference counting for memory management.

From 62bc46e9ac2f01979c39224fe5412e6d3df41b22 Mon Sep 17 00:00:00 2001
From: Tim Felgentreff <tim.felgentreff@oracle.com>
Date: Fri, 8 May 2026 00:10:32 +0200
Subject: [PATCH 4/4] Guard against native extensions on virtual threads

---
 .../python/processor/CApiBuiltinsProcessor.java | 10 ++++++++++
 .../builtins/objects/cext/capi/CApiContext.java |  3 +++
 .../graal/python/nodes/ErrorMessages.java       |  2 ++
 .../graal/python/runtime/PythonContext.java     | 17 ++++++++++++++++-
 .../nativeaccess/NativeAccessSupport.java       |  6 ++++++
 .../nativeaccess/NativeAccessSupportJdk21.java  |  5 +++++
 6 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/graalpython/com.oracle.graal.python.processor/src/com/oracle/graal/python/processor/CApiBuiltinsProcessor.java b/graalpython/com.oracle.graal.python.processor/src/com/oracle/graal/python/processor/CApiBuiltinsProcessor.java
index d9b6ed0b26..f5622e81a4 100644
--- a/graalpython/com.oracle.graal.python.processor/src/com/oracle/graal/python/processor/CApiBuiltinsProcessor.java
+++ b/graalpython/com.oracle.graal.python.processor/src/com/oracle/graal/python/processor/CApiBuiltinsProcessor.java
@@ -1502,6 +1502,11 @@ private void generateNativeAccessSupport(Element[] origins) throws IOException {
         lines.add("        return Linker.nativeLinker().upcallStub(staticMethodHandle, functionDescriptor, (Arena) arena).address();");
         lines.add("    }");
         lines.add("");
+        lines.add("    @Override");
+        lines.add("    protected boolean isCurrentThreadVirtualImpl() {");
+        lines.add("        return Thread.currentThread().isVirtual();");
+        lines.add("    }");
+        lines.add("");
         lines.add("    private static FunctionDescriptor createFunctionDescriptor(NativeSimpleType resType, NativeSimpleType[] argTypes) {");
         lines.add("        MemoryLayout[] argLayouts = new MemoryLayout[argTypes.length];");
         lines.add("        for (int i = 0; i < argTypes.length; i++) {");
@@ -1598,6 +1603,11 @@ private void generateDummyNativeAccessSupport(Element[] origins) throws IOExcept
         lines.add("    protected long createClosureImpl(MethodHandle staticMethodHandle, NativeSimpleType resType, NativeSimpleType[] argTypes, Object arena) {");
         lines.add("        throw unsupported();");
         lines.add("    }");
+        lines.add("");
+        lines.add("    @Override");
+        lines.add("    protected boolean isCurrentThreadVirtualImpl() {");
+        lines.add("        return false;");
+        lines.add("    }");
         lines.add("}");
 
         var file = processingEnv.getFiler().createSourceFile(NATIVE_ACCESS_PACKAGE + "." + NATIVE_ACCESS_SUPPORT_IMPL_CLASS_NAME, origins);
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
index 9d826b4afa..3ae238e251 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/cext/capi/CApiContext.java
@@ -891,6 +891,9 @@ private static CApiContext loadCApi(Node node, PythonContext context, TruffleStr
         String libName = PythonContext.getSupportLibName("python-native");
         final TruffleFile capiFile = homePath.resolve(libName).getCanonicalFile();
         try {
+            if (PythonContext.isCurrentThreadVirtual()) {
+                throw new ApiInitException(ErrorMessages.NATIVE_EXTENSIONS_VIRTUAL_THREAD);
+            }
             boolean useNative = true;
             boolean isolateNative = PythonOptions.IsolateNativeModules.getValue(env.getOptions());
             final NativeLibraryLocator loc;
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/ErrorMessages.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/ErrorMessages.java
index 72ce90563f..a65a2ccd86 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/ErrorMessages.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/ErrorMessages.java
@@ -1305,6 +1305,8 @@ public abstract class ErrorMessages {
     public static final TruffleString NFI_NOT_AVAILABLE = tsLiteral("GraalPy option '%s' is set to '%s, but the 'nfi' language, which is required for this feature, is not available. " +
                     "If this is a GraalPy standalone distribution: this indicates internal error. If GraalPy was used as a Maven dependency: " +
                     "are you missing a runtime dependency 'org.graalvm.truffle:truffle-nfi-libffi', which should be a dependency of 'org.graalvm.polyglot:python{-community}'?");
+    public static final TruffleString NATIVE_EXTENSIONS_VIRTUAL_THREAD = tsLiteral("Python native extensions cannot be used from Java virtual threads. " +
+                    "Run Python code that may load or call native extensions on a platform thread.");
 
     // AST Validator
     public static final TruffleString ANN_ASSIGN_WITH_SIMPLE_NON_NAME_TARGET = tsLiteral("AnnAssign with simple non-Name target");
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java
index f285b99d13..b7e3c64405 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java
@@ -171,6 +171,7 @@
 import com.oracle.graal.python.runtime.exception.PythonExitException;
 import com.oracle.graal.python.runtime.exception.PythonThreadKillException;
 import com.oracle.graal.python.runtime.locale.PythonLocale;
+import com.oracle.graal.python.runtime.nativeaccess.NativeAccessSupport;
 import com.oracle.graal.python.runtime.nativeaccess.NativeContext;
 import com.oracle.graal.python.runtime.nativeaccess.NativeMemory;
 import com.oracle.graal.python.runtime.object.IDUtils;
@@ -247,6 +248,10 @@ public final class PythonContext extends Python3Core {
     // Used for testing only.
     public boolean wasStackWalk;
 
+    public static boolean isCurrentThreadVirtual() {
+        return NativeAccessSupport.isCurrentThreadVirtual();
+    }
+
     @TruffleBoundary
     public static String getSupportLibName(PythonOS os, String libName) {
         // note: this should be aligned with MX's "lib" substitution
@@ -2722,7 +2727,7 @@ public void initializeMultiThreading() {
     public void attachThread(Thread thread, ContextThreadLocal<PythonThreadState> threadState) {
         CompilerAsserts.neverPartOfCompilation();
         PythonThreadState pythonThreadState = threadState.get(thread);
-        threadStateMapping.put(thread, pythonThreadState);
+        PythonThreadState previousThreadState = threadStateMapping.put(thread, pythonThreadState);
         ReentrantLock initLock = getcApiInitializationLock();
         /*
          * Synchronize with C API initialization so that we do not miss eager initialization of this
@@ -2734,9 +2739,19 @@ public void attachThread(Thread thread, ContextThreadLocal<PythonThreadState> th
         initLock.lock();
         try {
             if (getCApiState() == CApiState.INITIALIZED) {
+                if (isCurrentThreadVirtual()) {
+                    throw PRaiseNode.raiseStatic(getLanguage().unavailableSafepointLocation, SystemError, ErrorMessages.NATIVE_EXTENSIONS_VIRTUAL_THREAD);
+                }
                 // initialize this thread's native TLS slot eagerly instead of on first use
                 initializeNativeThreadState(pythonThreadState);
             }
+        } catch (PException e) {
+            if (previousThreadState == null) {
+                threadStateMapping.remove(thread);
+            } else {
+                threadStateMapping.put(thread, previousThreadState);
+            }
+            throw e;
         } finally {
             initLock.unlock();
         }
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupport.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupport.java
index 643e58157d..4dd4f4a352 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupport.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupport.java
@@ -114,6 +114,10 @@ static long createClosure(MethodHandle staticMethodHandle, NativeSimpleType resT
         return INSTANCE.createClosureImpl(staticMethodHandle, resType, argTypes, arena);
     }
 
+    public static boolean isCurrentThreadVirtual() {
+        return INSTANCE.isCurrentThreadVirtualImpl();
+    }
+
     private MethodHandle createTypedDowncallHandle(NativeSimpleType resType, NativeSimpleType... argTypes) {
         Class<?>[] parameterTypes = new Class<?>[argTypes.length + 1];
         parameterTypes[0] = long.class;
@@ -134,4 +138,6 @@ private MethodHandle createTypedDowncallHandle(NativeSimpleType resType, NativeS
     protected abstract MethodHandle createDowncallHandleImpl(MethodType methodType, boolean critical);
 
     protected abstract long createClosureImpl(MethodHandle staticMethodHandle, NativeSimpleType resType, NativeSimpleType[] argTypes, Object arena);
+
+    protected abstract boolean isCurrentThreadVirtualImpl();
 }
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupportJdk21.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupportJdk21.java
index 3e006c9a77..0e32cace08 100644
--- a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupportJdk21.java
+++ b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/nativeaccess/NativeAccessSupportJdk21.java
@@ -72,4 +72,9 @@ protected MethodHandle createDowncallHandleImpl(MethodType methodType, boolean c
     protected long createClosureImpl(MethodHandle staticMethodHandle, NativeSimpleType resType, NativeSimpleType[] argTypes, Object arena) {
         throw unsupported();
     }
+
+    @Override
+    protected boolean isCurrentThreadVirtualImpl() {
+        return false;
+    }
 }