Separate environment building from worker processes

ResidentWorker built its own environment, conflating two lifetimes: an
environment is built once and can serve any number of worker processes,
while a worker is one process with its own imports, exported state and
memory. Two workers on one environment would each have built it.

LazyEnvironment now builds an environment once, reporting to its build
listeners, and serializes builds of same-named environments, which
share a directory on disk. ResidentWorker is one process running in a
LazyEnvironment. ResidentWorkerService owns the policy of how many
workers an environment gets, which is still exactly one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ctrueden

README.md

@@ -67,7 +67,9 @@ if "model" not in globals():
     task.export(model=model)
 ```
 
-Runs on the same environment execute one at a time. Each run appears in the
+Runs on the same worker execute one at a time; since each environment
+currently gets a single worker, so do runs on the same environment, while
+runs on different environments proceed in parallel. Each run appears in the
 application's task list, where it can be canceled. A script can notice
 cancelation by checking `task.cancel_requested`; if it has not stopped a few
 seconds after being canceled, its worker process is stopped, and the next

src/main/java/org/scijava/plugins/scripting/appose/python/ApposePythonScriptEngine.java

@@ -273,7 +273,7 @@ private Object runTask(final ResidentWorker worker,
 		}
 		catch (final BuildException e) {
 			throw scriptException("Failed to build Appose environment '" + worker
-				.name() + "': " + e.getMessage(), e);
+				.environment().name() + "': " + e.getMessage(), e);
 		}
 		catch (final TaskException e) {
 			if (progress != null && progress.isCanceled()) {
@@ -455,13 +455,13 @@ private ResidentWorker worker(final ScriptInfo info) throws ScriptException {
 		final String scheme = info.get("scheme");
 
 		return workerService.worker(envName, scheme + "\n" + content, () -> {
-			Builder<?> builder = Appose.content(content);
-			if (scheme != null) builder = builder.scheme(scheme);
+			final Builder<?> builder = Appose.content(content);
+			return scheme == null ? builder : builder.scheme(scheme);
+		},
 			// Note: On Windows, importing numpy from a task hangs unless numpy
 			// was imported during worker initialization.
-			return new ResidentWorker(envName, builder.name(envName), env -> env
-				.python().init("try:\n    import numpy\nexcept ImportError:\n    pass\n"));
-		});
+			env -> env.python().init(
+				"try:\n    import numpy\nexcept ImportError:\n    pass\n"));
 	}
 
 	/** Resolves an (optionally relative) env file path against the script path. */

src/main/java/org/scijava/plugins/scripting/appose/python/_internal/LazyEnvironment.java

@@ -0,0 +1,111 @@
+/*
+ * #%L
+ * Python scripting language plugin backed by Appose.
+ * %%
+ * Copyright (C) 2026 SciJava developers.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package org.scijava.plugins.scripting.appose.python._internal;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+import org.apposed.appose.BuildException;
+import org.apposed.appose.Builder;
+import org.apposed.appose.Environment;
+
+/**
+ * An Appose environment that is built on first use, once, and then shared by
+ * any number of {@link ResidentWorker}s.
+ * <p>
+ * Builds of environments with the same name are serialized, even across
+ * instances, because they share a directory on disk: e.g. when the
+ * environment's configuration changes while an older build is still running.
+ * </p>
+ */
+public class LazyEnvironment {
+
+	/** Locks serializing builds, keyed by environment name. */
+	private static final Map<String, Object> BUILD_LOCKS =
+		new ConcurrentHashMap<>();
+
+	private final String name;
+	private final Builder<?> builder;
+	private final List<BuildListener> listeners = new CopyOnWriteArrayList<>();
+
+	private volatile Environment env;
+
+	/**
+	 * @param name Name of the environment, as reported to listeners, and as
+	 *          given to the builder.
+	 * @param builder Builder for the environment; built on first use.
+	 */
+	public LazyEnvironment(final String name, final Builder<?> builder) {
+		this.name = name;
+		// Note: Subscribe once, here, and dispatch to the current listeners,
+		// because builders accumulate subscribers with every call.
+		this.builder = builder.name(name) //
+			.subscribeProgress((title, current, maximum) -> listeners.forEach(
+				l -> l.buildProgress(name, title, current, maximum))) //
+			.subscribeOutput(text -> listeners.forEach(l -> l.buildOutput(name,
+				text))) //
+			.subscribeError(text -> listeners.forEach(l -> l.buildError(name,
+				text)));
+	}
+
+	public String name() {
+		return name;
+	}
+
+	public LazyEnvironment addBuildListener(final BuildListener listener) {
+		listeners.add(listener);
+		return this;
+	}
+
+	/** Whether the environment has been built by this instance. */
+	public boolean isBuilt() {
+		return env != null;
+	}
+
+	/** Gets the environment, building it if this is its first use. */
+	public Environment get() throws BuildException {
+		if (env != null) return env;
+		synchronized (BUILD_LOCKS.computeIfAbsent(name, k -> new Object())) {
+			if (env != null) return env;
+			listeners.forEach(l -> l.buildStarted(name));
+			try {
+				env = builder.build();
+			}
+			catch (final BuildException | RuntimeException exc) {
+				listeners.forEach(l -> l.buildFinished(name, exc));
+				throw exc;
+			}
+			listeners.forEach(l -> l.buildFinished(name, null));
+			return env;
+		}
+	}
+}

src/main/java/org/scijava/plugins/scripting/appose/python/_internal/ResidentWorker.java

@@ -31,23 +31,19 @@
 
 import java.io.IOException;
 import java.io.UncheckedIOException;
-import java.util.List;
 import java.util.Map;
-import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReentrantLock;
 import java.util.function.Consumer;
 import java.util.function.Function;
 
 import org.apposed.appose.BuildException;
-import org.apposed.appose.Builder;
 import org.apposed.appose.Environment;
 import org.apposed.appose.Service;
 
 /**
- * An Appose worker that stays resident across tasks: its environment is
- * built on first use, its worker process is started once and reused, and
- * both are released only on request.
+ * An Appose worker process that stays resident across tasks: it is started
+ * on first use, reused afterward, and ended only on request.
  * <p>
  * Keeping the worker alive is what makes repeated runs fast: modules the
  * worker has imported stay imported, and objects a task hands to
@@ -57,46 +53,35 @@
  * free it.
  * </p>
  * <p>
- * If the worker dies (e.g. it crashes, or {@link #kill()} is called), the
- * next task transparently starts a new one.
+ * A worker runs in a {@link LazyEnvironment}, which it builds if needed; any
+ * number of workers may share one environment. If the worker dies (e.g. it
+ * crashes, or {@link #kill()} is called), the next task transparently starts
+ * a new process.
  * </p>
  */
 public class ResidentWorker implements AutoCloseable {
 
-	private final String name;
-	private final Builder<?> builder;
+	private final LazyEnvironment environment;
 	private final Function<Environment, Service> launcher;
-	private final List<BuildListener> listeners = new CopyOnWriteArrayList<>();
 	private final Lock exclusive = new ReentrantLock();
 
 	private volatile Consumer<String> debug;
-	private Environment env;
 	private Service service;
 
 	/**
-	 * @param name Name of the environment, as reported to listeners.
-	 * @param builder Builder for the environment; built on first use.
+	 * @param environment Environment the worker runs in.
 	 * @param launcher Creates the worker's service from the built environment,
 	 *          e.g. {@code env -> env.python().init("import numpy")}.
 	 */
-	public ResidentWorker(final String name, final Builder<?> builder,
+	public ResidentWorker(final LazyEnvironment environment,
 		final Function<Environment, Service> launcher)
 	{
-		this.name = name;
+		this.environment = environment;
 		this.launcher = launcher;
-		// Note: Subscribe once, here, and dispatch to the current listeners,
-		// because builders accumulate subscribers with every call.
-		this.builder = builder //
-			.subscribeProgress((title, current, maximum) -> listeners.forEach(
-				l -> l.buildProgress(name, title, current, maximum))) //
-			.subscribeOutput(text -> listeners.forEach(l -> l.buildOutput(name,
-				text))) //
-			.subscribeError(text -> listeners.forEach(l -> l.buildError(name,
-				text)));
 	}
 
-	public String name() {
-		return name;
+	public LazyEnvironment environment() {
+		return environment;
 	}
 
 	/**
@@ -108,11 +93,6 @@ public Lock exclusive() {
 		return exclusive;
 	}
 
-	public ResidentWorker addBuildListener(final BuildListener listener) {
-		listeners.add(listener);
-		return this;
-	}
-
 	/**
 	 * Sets where the worker's debug output goes: stderr lines, non-protocol
 	 * stdout lines and protocol traffic, as described by
@@ -123,21 +103,6 @@ public void debug(final Consumer<String> listener) {
 		debug = listener;
 	}
 
-	/** Gets the environment, building it if this is its first use. */
-	public synchronized Environment environment() throws BuildException {
-		if (env != null) return env;
-		listeners.forEach(l -> l.buildStarted(name));
-		try {
-			env = builder.build();
-		}
-		catch (final BuildException | RuntimeException exc) {
-			listeners.forEach(l -> l.buildFinished(name, exc));
-			throw exc;
-		}
-		listeners.forEach(l -> l.buildFinished(name, null));
-		return env;
-	}
-
 	/**
 	 * Gets the worker's service, building the environment and starting the
 	 * worker process first if needed.
@@ -146,7 +111,7 @@ public synchronized Environment environment() throws BuildException {
 	 */
 	public synchronized Service service() throws BuildException {
 		if (service != null && service.isAlive()) return service;
-		final Service s = launcher.apply(environment());
+		final Service s = launcher.apply(environment.get());
 		s.debug(msg -> {
 			final Consumer<String> listener = debug;
 			if (listener != null) listener.accept(msg);
@@ -161,7 +126,7 @@ public synchronized Service service() throws BuildException {
 		return service;
 	}
 
-	/** Creates a task to run on the resident worker. */
+	/** Creates a task to run on this worker. */
 	public Service.Task task(final String script,
 		final Map<String, Object> inputs) throws BuildException
 	{

src/main/java/org/scijava/plugins/scripting/appose/python/_internal/ResidentWorkerService.java

@@ -33,8 +33,11 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
+import org.apposed.appose.Builder;
+import org.apposed.appose.Environment;
 import org.scijava.app.StatusService;
 import org.scijava.log.LogService;
 import org.scijava.plugin.Parameter;
@@ -45,9 +48,15 @@
 import org.scijava.task.TaskService;
 
 /**
- * Keeps one {@link ResidentWorker} per Appose environment for the lifetime of
- * the application context, showing environment builds as SciJava tasks, and
- * ending every worker when the context is disposed.
+ * Keeps Appose environments and their {@link ResidentWorker}s for the
+ * lifetime of the application context, showing environment builds as SciJava
+ * tasks, and ending every worker when the context is disposed.
+ * <p>
+ * Each environment currently gets exactly one worker. Several workers per
+ * environment would let runs proceed in parallel, but each worker holds its
+ * own copy of whatever a script loads (GPU memory included), and state kept
+ * via {@code task.export(...)} would live in only one of them.
+ * </p>
  */
 @Plugin(type = Service.class)
 public class ResidentWorkerService extends AbstractService implements
@@ -63,35 +72,38 @@ public class ResidentWorkerService extends AbstractService implements
 	@Parameter(required = false)
 	private LogService log;
 
-	/** Workers by environment name, each with the configuration it was made for. */
-	private final Map<String, Entry> workers = new HashMap<>();
+	/** Environments by name, each with its configuration and worker. */
+	private final Map<String, Entry> entries = new HashMap<>();
 
 	/**
-	 * Gets the resident worker for the named environment, creating it if
-	 * needed.
+	 * Gets the resident worker for the named environment, creating the
+	 * environment and worker if needed.
 	 * <p>
-	 * If the environment's configuration has changed since its worker was
-	 * created, as indicated by {@code config}, the old worker is released and
+	 * If the environment's configuration has changed since it was created, as
+	 * indicated by {@code config}, its old worker is released and both are
 	 * replaced, so that the next run uses the updated environment.
 	 * </p>
 	 *
 	 * @param name Name of the environment.
 	 * @param config The environment's configuration, e.g. its file contents.
-	 * @param factory Creates a worker for the environment.
+	 * @param builder Creates a builder for the environment.
+	 * @param launcher Creates a worker's service from the built environment.
 	 */
 	public ResidentWorker worker(final String name, final String config,
-		final Supplier<ResidentWorker> factory)
+		final Supplier<Builder<?>> builder,
+		final Function<Environment, org.apposed.appose.Service> launcher)
 	{
 		final ResidentWorker stale;
 		final ResidentWorker worker;
-		synchronized (workers) {
-			final Entry entry = workers.get(name);
+		synchronized (entries) {
+			final Entry entry = entries.get(name);
 			if (entry != null && entry.config.equals(config)) return entry.worker;
 			stale = entry == null ? null : entry.worker;
-			worker = factory.get();
-			worker.addBuildListener(SciJavaTasks.buildListener(taskService,
+			final LazyEnvironment env = new LazyEnvironment(name, builder.get());
+			env.addBuildListener(SciJavaTasks.buildListener(taskService,
 				statusService, log));
-			workers.put(name, new Entry(config, worker));
+			worker = new ResidentWorker(env, launcher);
+			entries.put(name, new Entry(config, worker));
 		}
 		if (stale != null) stale.release();
 		return worker;
@@ -100,8 +112,8 @@ public ResidentWorker worker(final String name, final String config,
 	/** Gets the current resident workers. */
 	public List<ResidentWorker> workers() {
 		final List<ResidentWorker> list = new ArrayList<>();
-		synchronized (workers) {
-			for (final Entry entry : workers.values()) list.add(entry.worker);
+		synchronized (entries) {
+			for (final Entry entry : entries.values()) list.add(entry.worker);
 		}
 		return list;
 	}
@@ -119,8 +131,8 @@ public void releaseAll() {
 	@Override
 	public void dispose() {
 		releaseAll();
-		synchronized (workers) {
-			workers.clear();
+		synchronized (entries) {
+			entries.clear();
 		}
 	}