mkdir elects one builder

 3 min Atomic directory creation elects one builder, but every error is treated as a lost race and losers continue before the winner is ready.

The election is one line:

# NOTE: Parent dirs in VIRTUAL_ENV must already exist; mkdir is atomic so we
# rely on that to avoid racing on venv creation.
! mkdir $VIRTUAL_ENV 2> /dev/null &&
  emit

mkdir creates the directory atomically, but the shell receives only success or failure. Given an existing writable parent, one of N concurrent runners creates the directory and the others fail with EEXIST. This code never tests for EEXIST, though. A missing parent, permissions failure, full filesystem, or I/O error takes the same negated branch and calls emit as if another process had won. The failure path needs to distinguish an existing claim from an inability to create one.

Even when failure really means EEXIST, the next line is a second defect. Every loser calls emit immediately, while the winner may still be creating the interpreter and activation script. Nothing waits for readiness. A caller can therefore source a path that does not exist yet or points into a half-built environment. The code prevents duplicate builders; it does not provide mutual exclusion between the builder and its readers.

A complete design needs a second state transition: build the environment at its final path, then publish a ready marker that readers wait for. Renaming a completed venv into place is not generally safe: activation scripts and installed commands can contain absolute paths to the build directory. Python’s venv documentation calls for recreating an environment when its location changes. Atomic claim and published readiness are different facts.

This came from pyproject/bin/activate: a universal bin/activate that ran an entire discover-or-create-venv program inside source $(...), using stdout to pass an activation-script path back to the caller, or /dev/null when the builder reported failure.

Winning the election creates an obligation, and the teardown is the other half of the pattern:

cleanup () { (($1)) && mv $VIRTUAL_ENV{,.$$} && rm -r $VIRTUAL_ENV.$$; } >&2

set -e; trap 'rc=$?; set +e; cleanup $rc; exit $rc' EXIT HUP INT QUIT TERM

On an ordinary nonzero failure after the mkdir, the half-built venv is renamed to $VIRTUAL_ENV.$$ first, and only then recursively deleted under its new name. Order is the point. Rename is atomic here, so observers see the lock position empty in one step; the slow rm -r then grinds away on a directory no other runner will ever look at. Delete in place instead and there’s a window—seconds long for a populated venv—where a concurrent runner sees a directory at the lock position and happily activates a venv that is actively being destroyed.

The shared signal/exit trap weakens even that boundary. It feeds the prior $? to cleanup, and cleanup acts only when that value is nonzero. A HUP, INT, QUIT, or TERM delivered after a successful command can therefore enter the trap with zero, skip cleanup, and exit successfully while leaving the claimed directory behind. The handler needed a signal-specific nonzero status instead of borrowing the previous command’s.

(Also visible: >&2 after the function’s closing brace. A redirection written after a function body is stored with the definition and applied at every invocation—this file puts its diagnostics on stderr that way, four functions in a row, keeping stdout clean for the one path it must emit.)

A builder killed by SIGKILL or power loss cannot run its trap. Its claimed directory remains, so a complete protocol also needs to detect and recover an abandoned build.