Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

12.4 KB
Raw Blame
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""One Mac, several worktrees: frame-time runs must not share the machine with Unity imports, builds, test runs or an open
Unity editor.

Usage: uv run tools/machine_lock.py (--shared | --exclusive) [--wait-unity] [--timeout SECONDS] -- <command> [args...]
--shared takes the machine lock shared (Unity builds, captures and edit-mode runs); --exclusive takes it alone (frame-time
profiles and boot budgets). In either mode, --wait-unity waits until no Unity is left running: no batch-mode Unity process,
and no process (an interactive editor included) holding any worktree's unity/Temp/UnityLockfile. Shared --wait-unity
requests also take a separate exclusive reservation (the lock path plus ".unity") before checking for Unity and hold it
while running their command. Two such requests therefore cannot both pass an idle check and launch together, even
before either child appears in process listings. Ordinary --shared requests and unwrapped Unity launches can still
overlap them; --exclusive excludes every participating shared holder. --timeout limits the Unity-process wait, not lock
acquisition. The lock file is
~/.cache/statecraft/machine.lock (fcntl.flock; STATECRAFT_MACHINE_LOCK overrides it), shared by every worktree of this
user. Exit code: the command's, 3 when --wait-unity times out, or 4 when Unity-process discovery fails.

Unity processes are recognised by their executable (`ps -o comm=`), never by argument text, so queued wrappers that
name Unity in their command line do not count (review C1). macOS flock does not queue fairly, so every request first
passes a gate (the same path plus ".gate"): it takes the gate exclusively, then the machine lock, then releases the gate.
A waiting exclusive request holds the gate until it has the lock, so no new shared holder gets in ahead of it and the
running ones drain (issue #207; before, a stream of shared jobs starved a profile, review M9).

When STATECRAFT_LOCK_HOLDER names a file, it writes "<this pid> <command pid>" there once the command has started:
the holder record tools/unity_postmerge.py uses to stop a hung Unity by its PID (T72). The command starts in its own
session/process group; its PID in that unchanged pair is also its process-group ID. SIGTERM, SIGHUP and SIGINT to the
holder are forwarded to that group, followed by bounded TERM/KILL cleanup before the lock is released. A terminal
Ctrl-C no longer reaches the child directly across the new session; the holder forwards SIGINT. Error paths also
retire the whole group. Descendants that deliberately leave the group are outside this lifetime guarantee.
Residual risk on macOS: SIGKILL or an OOM-kill of the holder itself cannot be caught, and there is no PDEATHSIG;
its lock can still close while its workload survives. This does not make holder SIGKILL safe."""
import argparse
import fcntl
import os
import signal
import subprocess
import sys
import time
from contextlib import ExitStack, contextmanager
from pathlib import Path

LOCK = Path(os.environ.get("STATECRAFT_MACHINE_LOCK", str(Path.home() / ".cache" / "statecraft" / "machine.lock")))
GATE = LOCK.with_name(LOCK.name + ".gate")
UNITY_LOCK = LOCK.with_name(LOCK.name + ".unity")
UNITY_EXE = "/Unity.app/Contents/MacOS/Unity"
HOLDER_ENV = "STATECRAFT_LOCK_HOLDER"


class DiscoveryFailed(RuntimeError):
    """Unity's state could not be determined, so the guarded command must not start."""


def checked_output(command: list[str]) -> str:
    try:
        result = subprocess.run(command, capture_output=True, text=True)
    except OSError as e:
        raise DiscoveryFailed(f"`{' '.join(command)}` could not start: {e}") from e
    if result.returncode != 0:
        detail = result.stderr.strip()
        suffix = f": {detail}" if detail else ""
        raise DiscoveryFailed(f"`{' '.join(command)}` exited {result.returncode}{suffix}")
    return result.stdout


def parse(argv: list[str]) -> argparse.Namespace:
    ap = argparse.ArgumentParser()
    mode = ap.add_mutually_exclusive_group(required=True)
    mode.add_argument("--shared", action="store_true")
    mode.add_argument("--exclusive", action="store_true")
    ap.add_argument("--wait-unity", action="store_true")
    ap.add_argument("--timeout", type=float, default=3600)
    ap.add_argument("command", nargs=argparse.REMAINDER)
    a = ap.parse_args(argv)
    if a.command and a.command[0] == "--":
        a.command = a.command[1:]
    if not a.command:
        ap.error("no command after --")
    return a


def _rows(ps_text: str) -> dict[int, str]:
    rows = {}
    for line in ps_text.splitlines():
        pid, _, rest = line.strip().partition(" ")
        if pid.isdigit():
            rows[int(pid)] = rest.strip()
    return rows


def batch_unity_pids(comm_text: str, args_text: str, exclude: set[int] | frozenset[int] = frozenset()) -> list[int]:
    """Pids whose executable (`ps -o comm=`, the binary's path) is Unity.app's Unity and whose arguments include
    -batchmode. Selected by executable, never by argument text: a queued `machine_lock.py --shared -- .../Unity
    -batchmode` wrapper and its `uv run` parent name Unity in their arguments and must not count (review C1)."""
    args = _rows(args_text)
    return sorted(pid for pid, exe in _rows(comm_text).items()
                  if exe.endswith(UNITY_EXE) and pid not in exclude and " -batchmode" in f" {args.get(pid, '')} ")


def unity_batch_pids() -> list[int]:
    def ps(field: str) -> str:
        return checked_output(["ps", "-axo", f"pid=,{field}="])
    return batch_unity_pids(ps("comm"), ps("args"), exclude={os.getpid()})


def worktrees() -> list[Path]:
    """Every worktree of this repository, so an editor open in any of them is seen."""
    text = checked_output(["git", "worktree", "list", "--porcelain"])
    return [Path(line[len("worktree "):]) for line in text.splitlines() if line.startswith("worktree ")]


def lockfile_holders(roots: list[Path], lsof=None) -> list[int]:
    """Pids holding any root's unity/Temp/UnityLockfile: every Unity editor with that project open, interactive or batch."""
    files = [str(p / "unity" / "Temp" / "UnityLockfile") for p in roots if (p / "unity" / "Temp" / "UnityLockfile").exists()]
    if not files:
        return []
    run = lsof or lsof_holders_output
    return sorted({int(p) for p in run(files).split() if p.isdigit()})


def lsof_holders_output(files: list[str]) -> str:
    """`lsof -t` exits 1 when nothing holds the files, and says "No such file" for one that vanished since the check:
    both mean no holder. Any other failure is a discovery failure. (macOS ships lsof 4.91, which has no -Q.)"""
    try:
        result = subprocess.run(["lsof", "-t", *files], capture_output=True, text=True)
    except OSError as e:
        raise DiscoveryFailed(f"`lsof` could not start: {e}") from e
    if result.returncode == 0:
        return result.stdout
    errors = [l for l in result.stderr.splitlines() if l.strip() and "No such file or directory" not in l]
    if result.returncode == 1 and not errors:
        return result.stdout
    raise DiscoveryFailed(f"`lsof` exited {result.returncode}: {result.stderr.strip()}")


def unity_pids() -> list[int]:
    return sorted(set(unity_batch_pids()) | set(lockfile_holders(worktrees())))


def wait_for_unity(timeout: float, pids=unity_pids, sleep=time.sleep, now=time.monotonic) -> bool:
    deadline = now() + timeout
    while True:
        busy = pids()
        if not busy:
            return True
        if now() >= deadline:
            return False
        print(f"machine_lock: waiting for Unity processes {busy} (batch runs, or an editor with a worktree open)", flush=True)
        sleep(10)


def stop_command_group(child: subprocess.Popen, grace: float = 1.0) -> None:
    """Retire our child's session, including grandchildren, before releasing flock."""
    def send(sig):
        try:
            os.killpg(child.pid, sig)
            return True
        except ProcessLookupError:
            return False
        except PermissionError:
            # Darwin reports EPERM, not ESRCH, for a group holding only zombies: our own not-yet-reaped child
            # (a forwarded signal often kills it first) or orphans awaiting their reaper. That group is retired.
            rows = subprocess.check_output(["ps", "-axo", "pgid=,stat="], text=True)
            if not any(int(parts[0]) == child.pid and not parts[1].startswith("Z")
                       for row in rows.splitlines() if len(parts := row.split()) == 2):
                return False
            if sig != 0:
                raise  # A live member refused the signal: never treat that as successful retirement.
            return True

    if send(signal.SIGTERM):
        deadline = time.monotonic() + grace
        while time.monotonic() < deadline:
            child.poll()  # reap the direct child even if grandchildren outlive it
            if not send(0):
                break
            time.sleep(0.02)
        send(signal.SIGKILL)
    child.wait()
    # Let killed descendants retire too; orphan zombies may await their system reaper.
    deadline = time.monotonic() + grace
    while send(0) and time.monotonic() < deadline:
        time.sleep(0.02)


@contextmanager
def hold(*, exclusive: bool = False):
    """Hold the canonical fair gate while cooperating Python tools run several related commands.

    Acquisition has no deadline: a waiting holder is never cancelled merely because its work deadline expired.
    Callers must check that deadline after acquisition, before starting their commands.
    """
    LOCK.parent.mkdir(parents=True, exist_ok=True)
    with open(GATE, "a+") as gate, open(LOCK, "a+") as lock:
        print(f"machine_lock: taking the machine lock ({'exclusive' if exclusive else 'shared'})", flush=True)
        fcntl.flock(gate, fcntl.LOCK_EX)
        fcntl.flock(lock, fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
        fcntl.flock(gate, fcntl.LOCK_UN)
        yield


def main(argv: list[str] | None = None) -> int:
    a = parse(sys.argv[1:] if argv is None else argv)
    with hold(exclusive=a.exclusive), ExitStack() as reservations:
        if a.shared and a.wait_unity:
            unity_lock = reservations.enter_context(open(UNITY_LOCK, "a+"))
            fcntl.flock(unity_lock, fcntl.LOCK_EX)
        if a.wait_unity:
            try:
                idle = wait_for_unity(a.timeout)
            except DiscoveryFailed as e:
                print(f"machine_lock: refused because Unity-process discovery failed: {e}", file=sys.stderr)
                return 4
            if not idle:
                print("machine_lock: timed out waiting for Unity")
                return 3
        child = None
        signals = (signal.SIGTERM, signal.SIGHUP, signal.SIGINT)
        previous = {}
        pending = None
        stopping = False

        def interrupted(signum, frame):
            nonlocal pending, stopping
            if child is None:
                # Popen may have spawned but not returned its handle yet. Defer until ownership is known.
                pending = pending or signum
                return
            try:
                os.killpg(child.pid, signum)
            except (ProcessLookupError, PermissionError):
                pass  # gone, or only its zombie is left (Darwin EPERM); stop_command_group below decides
            if not stopping:  # a second signal must not abort the cleanup already under way
                stopping = True
                raise SystemExit(128 + signum)

        try:
            for sig in signals:
                previous[sig] = signal.signal(sig, interrupted)
            # Do not block signals around spawn: the exec'd child would inherit the blocked mask.
            child = subprocess.Popen(a.command, start_new_session=True)
            if pending is not None:
                interrupted(pending, None)
            if record := os.environ.get(HOLDER_ENV):
                tmp = Path(record + ".tmp")
                tmp.write_text(f"{os.getpid()} {child.pid}\n")
                os.replace(tmp, record)
            return child.wait()
        finally:
            # Cleanup must finish under the lock even if another terminal signal arrives.
            stopping = True
            for sig in previous:
                signal.signal(sig, signal.SIG_IGN)
            try:
                if child is not None:
                    stop_command_group(child)
            finally:
                for sig, handler in previous.items():
                    signal.signal(sig, handler)


if __name__ == "__main__":
    sys.exit(main())