feat: named contexts are ephemeral

Signed-off-by: Leo Galambos <lg@hq.egothor.org>

.classpath

@@ -13,19 +13,6 @@
 			<attribute name="test" value="true"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="src" output="bin/main" path="src/main/resources">
-		<attributes>
-			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="src" output="bin/test" path="src/test/resources">
-		<attributes>
-			<attribute name="gradle_scope" value="test"/>
-			<attribute name="gradle_used_by_scope" value="test"/>
-			<attribute name="test" value="true"/>
-		</attributes>
-	</classpathentry>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-21/"/>
 	<classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
 	<classpathentry kind="output" path="bin/default"/>

src/main/java/conflux/Ctx.java

@@ -34,9 +34,12 @@
  */
 package conflux;
 
+import java.lang.ref.ReferenceQueue;
+import java.lang.ref.WeakReference;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 /**
  * A central context manager for storing and retrieving key-value pairs in a
@@ -61,17 +64,79 @@ public enum Ctx implements CtxInterface {
      */
     INSTANCE;
 
-    /**
-     * A registry of named contexts, allowing for multiple isolated logical
-     * contexts.
-     */
-    private final Map<String, CtxInterface> contexts = new ConcurrentHashMap<>();
     /**
      * The default context instance used by this enum singleton. All interface
      * method calls delegate to this context.
      */
     private final CtxInterface defaultCtx = new CtxInstance();
 
+    /**
+     * A registry of named contexts, allowing for multiple isolated logical
+     * contexts.
+     */
+    private final Map<String, NamedWeakRef> contexts = new ConcurrentHashMap<>();
+
+    /**
+     * A reference queue to learn when weakly referenced contexts are collected.
+     */
+    private final transient ReferenceQueue<CtxInterface> refQueue = new ReferenceQueue<>();
+
+    /**
+     * A weak reference wrapper that associates a {@link CtxInterface} instance (the
+     * referent) with its corresponding context name.
+     * <p>
+     * Instances of this class are enqueued into a {@link ReferenceQueue} once their
+     * referent becomes unreachable. The extra {@code name} field allows the owning
+     * registry to efficiently remove the corresponding entry from the context map
+     * without requiring a reverse lookup.
+     * </p>
+     *
+     * <h2>Usage</h2>
+     * <ul>
+     * <li>Created whenever a new named context is registered.</li>
+     * <li>Placed into a {@link ConcurrentHashMap} keyed by the same
+     * {@code name}.</li>
+     * <li>When the referent is garbage-collected, this reference is automatically
+     * enqueued, and the registry removes the map entry associated with
+     * {@link #name}.</li>
+     * </ul>
+     *
+     * <p>
+     * This design ensures that contexts are automatically deregistered when no
+     * strong references to them remain, preventing memory leaks while still
+     * allowing explicit removal via {@code removeContext}.
+     * </p>
+     */
+    private static final class NamedWeakRef extends WeakReference<CtxInterface> {
+        /**
+         * The context name associated with the referent.
+         */
+        private final String name;
+
+        /**
+         * Creates a new weak reference to the given context instance and associates it
+         * with the provided name.
+         *
+         * @param name     the context name; used as the key in the registry
+         * @param referent the context instance being weakly referenced
+         * @param q        the reference queue with which the weak reference is
+         *                 registered
+         */
+        private NamedWeakRef(String name, CtxInterface referent, ReferenceQueue<CtxInterface> q) {
+            super(referent, q);
+            this.name = name;
+        }
+    }
+
+    /**
+     * Remove collected references from map.
+     */
+    private void drainQueue() {
+        for (NamedWeakRef ref; (ref = (NamedWeakRef) refQueue.poll()) != null;) { // NOPMD
+            contexts.remove(ref.name, ref);
+        }
+    }
+
     /**
      * Returns a named context. If the context does not exist, it is lazily created.
      * 
@@ -82,7 +147,69 @@ public enum Ctx implements CtxInterface {
      * @return the associated context instance
      */
     public CtxInterface getContext(String name) {
-        return contexts.computeIfAbsent(name, k -> new CtxInstance());
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("name must not be null or blank");
+        }
+        drainQueue();
+        NamedWeakRef ref = contexts.compute(name, (k, existing) -> {
+            CtxInterface alive = existing == null ? null : existing.get();
+            if (alive != null) {
+                return existing;
+            }
+            CtxInterface created = new CtxInstance();
+            return new NamedWeakRef(k, created, refQueue);
+        });
+        CtxInterface ctx = ref.get();
+        if (ctx == null) {
+            CtxInterface created = new CtxInstance();
+            NamedWeakRef fresh = new NamedWeakRef(name, created, refQueue);
+            contexts.put(name, fresh);
+            ctx = created;
+        }
+        return ctx;
+    }
+
+    /**
+     * Removes a named context previously created via {@link #getContext(String)}.
+     * <p>
+     * The context is atomically removed from the internal registry and then
+     * {@linkplain CtxInterface#clear() cleared} to release stored values and
+     * listener references. This operation is thread-safe and idempotent: if the
+     * specified context does not exist, the method returns {@code false} and
+     * performs no action.
+     * </p>
+     * <p>
+     * Calling {@code getContext(name)} again after a successful removal will create
+     * a brand-new, empty context. The default/global context represented by
+     * {@link #INSTANCE} is not affected.
+     * </p>
+     *
+     * @param name the name of the context to remove; must not be {@code null} or
+     *             blank
+     * @return {@code true} if a context with the given name existed and was
+     *         removed; {@code false} otherwise
+     * @throws IllegalArgumentException if {@code name} is {@code null} or blank
+     * @implNote Uses {@link ConcurrentHashMap#remove(Object)} for atomic removal,
+     *           then invokes {@link CtxInterface#clear()} on the removed instance.
+     * @since 2025.08
+     */
+    public boolean removeContext(String name) {
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("name must not be null or blank");
+        }
+        drainQueue();
+        NamedWeakRef ref = contexts.remove(name);
+        if (ref == null) {
+            return false; // NOPMD
+        }
+        CtxInterface ctx = ref.get();
+        if (ctx != null) {
+            try {
+                ctx.clear();
+            } catch (RuntimeException ignore) { // NOPMD
+            }
+        }
+        return true;
     }
 
     /**
@@ -91,7 +218,9 @@ public enum Ctx implements CtxInterface {
      * @return an immutable set of context names
      */
     public Set<String> contextNames() {
-        return Set.copyOf(contexts.keySet());
+        drainQueue();
+        return Set.copyOf(contexts.entrySet().stream().filter(e -> e.getValue().get() != null).map(Map.Entry::getKey)
+                .collect(Collectors.toSet()));
     }
 
     /**