Sticky session for ref() handles — protect idle instances with active handles from cleanup

Add PythonEmbed.hasActiveHandles() to check for active ref handles (O(1), thread-safe)

Modify cleanupIdleInstances() to skip instances with active handles

Deprecate proxy(int refId, Class) in both PythonEmbed and PythonEmbedPool

Update pool.ref() Javadoc to reflect idle cleanup safety guarantee

Author: white

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.0.5] - 2026-06-27
+
+- [python-embed-runtime](python-embed-runtime/CHANGELOG.md) (1.0.3) — Sticky Session for `ref()` handles: idle scale-down no longer invalidates active handles; `proxy(int refId, Class)` deprecated
+
 ## [1.0.4] - 2026-06-26
 
 - [python-embed-build-common](python-embed-build-common/CHANGELOG.md) (1.0.2) — shared build logic for Gradle/Maven plugins
@@ -46,6 +50,7 @@ Modules are now independently versioned with per-module changelogs:
 - Close hook support for resource cleanup
 - 13 example applications in `python-embed-examples`
 
+[1.0.5]: See per-module changelogs above
 [1.0.4]: See per-module changelogs above
 [1.0.3]: See per-module changelogs above
 [1.0.2]: See per-module changelogs above

python-embed-runtime/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.0.3] - 2026-06-27
+
+### Added
+- Sticky Session for `ref()` handles: `PythonEmbed.hasActiveHandles()` ensures instances with live handles are excluded from idle scale-down
+
+### Deprecated
+- `PythonEmbedPool.proxy(int refId, Class)` and `PythonEmbed.proxy(int refId, Class)` — use `proxy(PythonHandle, Class)` or `proxy(String, Class)` instead
+
 ## [1.0.2] - 2026-06-24
 
 ### Changed
@@ -28,6 +36,7 @@
 - Periodic health check with RSS memory, ref count, and GC status reporting
 - Close hook support for resource cleanup
 
+[runtime-v1.0.3]: https://github.com/howtis/python-embed/releases/tag/runtime-v1.0.3
 [runtime-v1.0.2]: https://github.com/howtis/python-embed/releases/tag/runtime-v1.0.2
 [runtime-v1.0.1]: https://github.com/howtis/python-embed/releases/tag/v1.0.1
 [runtime-v1.0.0]: https://github.com/howtis/python-embed/releases/tag/v1.0.0

python-embed-runtime/src/main/java/io/github/howtis/pythonembed/PythonEmbed.java

@@ -655,18 +655,18 @@ public PythonHandle ref(String variableName) {
      *
      * <p>Python exceptions are propagated as {@link PythonExecutionException}.
      *
-     * <pre>{@code
-     * PythonHandle handle = py.ref("my_object");
-     * MyInterface obj = py.proxy(handle.getRefId(), MyInterface.class);
-     * String result = obj.process("input");  // calls my_object.process("input")
-     * }</pre>
+     * @deprecated Prefer {@link #proxy(String, Class)} which manages handle
+     *             lifecycle automatically, or use
+     *             {@link PythonEmbedPool#proxy(PythonHandle, Class)} for
+     *             pool-scoped proxies.
      *
      * @param <T>            the interface type
      * @param refId          the Python object reference ID from {@link PythonHandle#refId()}
      * @param interfaceClass the Java interface to proxy
      * @return a dynamic proxy implementing the given interface
      * @throws IllegalArgumentException if {@code interfaceClass} is not an interface
      */
+    @Deprecated(since = "1.0.5", forRemoval = false)
     @SuppressWarnings("unchecked")
     public <T> T proxy(int refId, Class<T> interfaceClass) {
         if (!interfaceClass.isInterface()) {
@@ -794,6 +794,10 @@ boolean isOpen() {
         return processManager.isRunning();
     }
 
+    boolean hasActiveHandles() {
+        return !handles.isEmpty();
+    }
+
     long getPid() {
         return processManager.getPid();
     }

python-embed-runtime/src/main/java/io/github/howtis/pythonembed/PythonEmbedPool.java

@@ -506,10 +506,9 @@ public CompletableFuture<Iterator<PythonValue>> stream(String code, long pollTim
     /**
      * Creates a handle to a Python variable asynchronously.
      *
-     * <p><b>Important:</b> The returned handle is bound to a specific
-     * {@link PythonEmbed} instance. If that instance is removed during
-     * idle scale-down, the handle becomes invalid. Callers should
-     * complete their work with the handle promptly.
+     * <p>The returned handle is bound to a specific {@link PythonEmbed}
+     * instance. As long as the handle has not been {@link PythonHandle#release() released},
+     * the owning instance is protected from idle scale-down.
      *
      * @param variableName the name of an existing Python variable
      * @return a future that completes with the handle
@@ -560,19 +559,19 @@ public <T> T proxy(PythonHandle handle, Class<T> interfaceClass) {
      * Creates a dynamic proxy that wraps a Python object as a Java interface,
      * with each method call acquiring and releasing a pool instance.
      *
-     *
-     * <pre>{@code
-     * PythonHandle handle = pool.ref("my_object").get();
-     * MyInterface obj = pool.proxy(handle, MyInterface.class);
-     * String result = obj.process("input");
-     * }</pre>
+     * @deprecated This method is inherently unsafe because {@code refId}
+     *             refers to an object in a specific Python process, but each
+     *             method call acquires a potentially different pool instance.
+     *             Use {@link #proxy(PythonHandle, Class)} instead, which routes
+     *             calls directly to the handle's owning instance.
      *
      * @param <T>            the interface type
      * @param refId          the Python object reference ID from {@link PythonHandle#refId()}
      * @param interfaceClass the Java interface to proxy
      * @return a dynamic proxy implementing the given interface
      * @throws IllegalArgumentException if {@code interfaceClass} is not an interface
      */
+    @Deprecated(since = "1.0.5", forRemoval = false)
     @SuppressWarnings("unchecked")
     public <T> T proxy(int refId, Class<T> interfaceClass) {
         if (!interfaceClass.isInterface()) {
@@ -1085,9 +1084,11 @@ private void cleanupIdleInstances() {
         while (it.hasNext()) {
             PooledInstance pi = it.next();
             if (currentSize.get() <= minPool) break;
-            if (!pi.busy && (now - pi.lastUsedAt) >= idleTimeoutMs) {
+            if (!pi.busy && !pi.embed.hasActiveHandles()
+                    && (now - pi.lastUsedAt) >= idleTimeoutMs) {
                 synchronized (pi) {
-                    if (!pi.busy && (now - pi.lastUsedAt) >= idleTimeoutMs) {
+                    if (!pi.busy && !pi.embed.hasActiveHandles()
+                            && (now - pi.lastUsedAt) >= idleTimeoutMs) {
                         if (pi.removed) continue;
                         pi.removed = true;
                         if (currentSize.decrementAndGet() >= minPool) {

python-embed-runtime/src/test/java/io/github/howtis/pythonembed/PythonEmbedPoolTest.java

@@ -1328,6 +1328,95 @@ void ref_nonExistentVariable_propagatesError() {
         assertTrue(ex.getCause().getMessage().contains("NameError"));
     }
 
+    @Test
+    @Timeout(value = 10, unit = TimeUnit.SECONDS)
+    void hasActiveHandles_refCountsHandle() throws Exception {
+        // Set up the variable on all instances
+        for (int i = 0; i < pool.size(); i++) {
+            pool.exec("h_test = 'active'").get(3, TimeUnit.SECONDS);
+        }
+        PythonHandle handle = pool.ref("h_test").get(3, TimeUnit.SECONDS);
+        assertNotNull(handle);
+        // While handle is alive, the owning embed must have active handles
+        PythonEmbed embed = handle.owner();
+        assertTrue(embed.hasActiveHandles());
+
+        handle.release();
+        // After release, no active handles remain
+        assertFalse(embed.hasActiveHandles());
+    }
+
+    @Test
+    @Timeout(value = 30, unit = TimeUnit.SECONDS)
+    void ref_handleSurvivesIdleCleanup() throws Exception {
+        PythonEmbedPool dynPool = PythonEmbedPool.builder().minPool(1).maxPool(3).idleTimeoutMs(0).build();
+        try {
+            assertEquals(1, dynPool.size());
+
+            // Scale up to have extra idle instances
+            CompletableFuture<?>[] tasks = new CompletableFuture[3];
+            for (int i = 0; i < 3; i++) {
+                tasks[i] = dynPool.eval("42");
+            }
+            CompletableFuture.allOf(tasks).get(10, TimeUnit.SECONDS);
+            int afterScaleUp = dynPool.size();
+            assertTrue(afterScaleUp >= 2, "Pool should have scaled up");
+
+            // Set up a variable on all instances
+            for (int i = 0; i < afterScaleUp; i++) {
+                dynPool.exec("sv = 'survive'").get(3, TimeUnit.SECONDS);
+            }
+
+            // Create a handle — this should pin its owning instance
+            PythonHandle handle = dynPool.ref("sv").get(3, TimeUnit.SECONDS);
+            assertNotNull(handle);
+
+            // Run idle cleanup — handle's instance should survive
+            dynPool.runMaintenance();
+
+            // The handle should still be usable (not invalidated by cleanup)
+            assertEquals("str", handle.pythonType());
+
+            handle.release();
+        } finally {
+            dynPool.close();
+        }
+    }
+
+    @Test
+    @Timeout(value = 30, unit = TimeUnit.SECONDS)
+    void ref_releasedHandle_cleanedUpNormally() throws Exception {
+        PythonEmbedPool dynPool = PythonEmbedPool.builder().minPool(1).maxPool(3).idleTimeoutMs(0).build();
+        try {
+            assertEquals(1, dynPool.size());
+
+            // Scale up to have extra idle instances
+            CompletableFuture<?>[] tasks = new CompletableFuture[3];
+            for (int i = 0; i < 3; i++) {
+                tasks[i] = dynPool.eval("42");
+            }
+            CompletableFuture.allOf(tasks).get(10, TimeUnit.SECONDS);
+            int afterScaleUp = dynPool.size();
+            assertTrue(afterScaleUp >= 2, "Pool should have scaled up");
+
+            // Set up a variable on all instances
+            for (int i = 0; i < afterScaleUp; i++) {
+                dynPool.exec("rn = 'normal'").get(3, TimeUnit.SECONDS);
+            }
+
+            // Create and immediately release a handle
+            PythonHandle handle = dynPool.ref("rn").get(3, TimeUnit.SECONDS);
+            handle.release();
+
+            // After release, idle cleanup should remove the extra instance
+            dynPool.runMaintenance();
+
+            assertEquals(1, dynPool.size(), "Released handle should allow idle cleanup");
+        } finally {
+            dynPool.close();
+        }
+    }
+
     // ---- proxy shortcut ----
 
     @Test