reslock 0.1.0__tar.gz

reslock-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.pyright/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db

reslock-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: reslock
+Version: 0.1.0
+Summary: Resource lock manager for coordinating shared system resources (GPU VRAM, RAM, CPU) across processes
+Project-URL: Homepage, https://github.com/mo22/reslock
+Project-URL: Repository, https://github.com/mo22/reslock
+Author-email: Moritz Möller <mm@mxs.de>
+License-Expression: MIT
+Keywords: gpu,lock,resource,scheduling,vram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: portalocker>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# reslock
+
+Resource lock manager for coordinating shared system resources (GPU VRAM, RAM, CPU cores) across multiple processes on a single machine.
+
+## Problem
+
+Multiple GPU-consuming processes (llama.cpp, whisper, vLLM, training jobs) compete for limited resources — especially VRAM. Without coordination, they OOM or degrade each other.
+
+## How it works
+
+- All coordination happens through a single JSON state file — no daemon required
+- Processes coordinate via file locking (held only during reads/writes, not for lease duration)
+- Dead processes are automatically cleaned up via PID checking
+- Priority queue determines which waiter gets resources next
+- Reclaimable leases allow loaded models to be preempted by higher-priority work
+
+## Install
+
+```bash
+pip install reslock
+```
+
+## Python API
+
+```python
+from reslock import ResourcePool
+
+pool = ResourcePool()  # uses ~/.reslock/state.json
+
+# Context manager — blocks until resources are available
+with pool.acquire(vram_mb=4000, priority=5, label="whisper") as lease:
+    run_whisper(audio_file)
+
+# Non-blocking
+lease = pool.try_acquire(vram_mb=4000)
+if lease:
+    try:
+        do_work()
+    finally:
+        lease.release()
+
+# Async
+async with pool.acquire_async(vram_mb=4000) as lease:
+    await run_inference()
+
+# Reclaimable lease — can be preempted
+lease = pool.acquire(vram_mb=4000, reclaimable=True)
+load_model()
+# ... later:
+if lease.reclaim_requested:
+    unload_model()
+    lease.release()
+
+# Check status
+status = pool.status()
+print(status.available)  # free resources
+```
+
+## CLI
+
+```bash
+# Initialize (auto-detects GPU)
+reslock init
+
+# Set resources manually
+reslock set vram_mb 24000
+reslock set gpu_slots 2
+
+# Show status
+reslock status
+
+# Run a command with reserved resources
+reslock run --vram 4G llama-cli --model model.gguf
+reslock run --vram 8G --priority 10 --label "llama-70b" llama-cli ...
+reslock run --vram 4G --ram 16G --cpu 4 python train.py
+
+# Manage leases
+reslock list
+reslock release abc-123
+reslock release --label whisper
+reslock reset
+```
+
+## How resources work
+
+Resources are named quantities with a total capacity. Resource names are arbitrary strings — define whatever you need:
+
+```bash
+reslock set vram_mb 24000
+reslock set ram_mb 65536
+reslock set gpu_slots 2
+```
+
+Leases reserve amounts from these pools. When a lease is released (or its process dies), the resources become available again.
+
+## Priority queue
+
+When resources aren't immediately available, requests enter a priority queue. Higher priority number = more urgent. Ties are broken by arrival time (FIFO).
+
+## Reclaimable leases
+
+A process can mark its lease as **reclaimable** — "I'm using this, but can give it up if needed." When a higher-priority request needs those resources, `reclaim_requested` is set to `True`. The lease holder cooperates by releasing.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```

reslock-0.1.0/README.md

@@ -0,0 +1,110 @@
+# reslock
+
+Resource lock manager for coordinating shared system resources (GPU VRAM, RAM, CPU cores) across multiple processes on a single machine.
+
+## Problem
+
+Multiple GPU-consuming processes (llama.cpp, whisper, vLLM, training jobs) compete for limited resources — especially VRAM. Without coordination, they OOM or degrade each other.
+
+## How it works
+
+- All coordination happens through a single JSON state file — no daemon required
+- Processes coordinate via file locking (held only during reads/writes, not for lease duration)
+- Dead processes are automatically cleaned up via PID checking
+- Priority queue determines which waiter gets resources next
+- Reclaimable leases allow loaded models to be preempted by higher-priority work
+
+## Install
+
+```bash
+pip install reslock
+```
+
+## Python API
+
+```python
+from reslock import ResourcePool
+
+pool = ResourcePool()  # uses ~/.reslock/state.json
+
+# Context manager — blocks until resources are available
+with pool.acquire(vram_mb=4000, priority=5, label="whisper") as lease:
+    run_whisper(audio_file)
+
+# Non-blocking
+lease = pool.try_acquire(vram_mb=4000)
+if lease:
+    try:
+        do_work()
+    finally:
+        lease.release()
+
+# Async
+async with pool.acquire_async(vram_mb=4000) as lease:
+    await run_inference()
+
+# Reclaimable lease — can be preempted
+lease = pool.acquire(vram_mb=4000, reclaimable=True)
+load_model()
+# ... later:
+if lease.reclaim_requested:
+    unload_model()
+    lease.release()
+
+# Check status
+status = pool.status()
+print(status.available)  # free resources
+```
+
+## CLI
+
+```bash
+# Initialize (auto-detects GPU)
+reslock init
+
+# Set resources manually
+reslock set vram_mb 24000
+reslock set gpu_slots 2
+
+# Show status
+reslock status
+
+# Run a command with reserved resources
+reslock run --vram 4G llama-cli --model model.gguf
+reslock run --vram 8G --priority 10 --label "llama-70b" llama-cli ...
+reslock run --vram 4G --ram 16G --cpu 4 python train.py
+
+# Manage leases
+reslock list
+reslock release abc-123
+reslock release --label whisper
+reslock reset
+```
+
+## How resources work
+
+Resources are named quantities with a total capacity. Resource names are arbitrary strings — define whatever you need:
+
+```bash
+reslock set vram_mb 24000
+reslock set ram_mb 65536
+reslock set gpu_slots 2
+```
+
+Leases reserve amounts from these pools. When a lease is released (or its process dies), the resources become available again.
+
+## Priority queue
+
+When resources aren't immediately available, requests enter a priority queue. Higher priority number = more urgent. Ties are broken by arrival time (FIFO).
+
+## Reclaimable leases
+
+A process can mark its lease as **reclaimable** — "I'm using this, but can give it up if needed." When a higher-priority request needs those resources, `reclaim_requested` is set to `True`. The lease holder cooperates by releasing.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```

reslock-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "reslock"
+version = "0.1.0"
+description = "Resource lock manager for coordinating shared system resources (GPU VRAM, RAM, CPU) across processes"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Moritz Möller", email = "mm@mxs.de" }]
+keywords = ["gpu", "vram", "resource", "lock", "scheduling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "portalocker>=2.0.0",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+    "pyright>=1.1.0",
+]
+
+[project.scripts]
+reslock = "reslock.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mo22/reslock"
+Repository = "https://github.com/mo22/reslock"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reslock"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/reslock"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # function calls in argument defaults (needed for Click)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["reslock"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+ignore = ["**/node_modules", "**/__pycache__"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

reslock-0.1.0/src/reslock/__init__.py

@@ -0,0 +1,8 @@
+"""reslock — Resource lock manager for coordinating shared system resources."""
+
+from __future__ import annotations
+
+from reslock.models import Lease, PoolStatus, QueueEntry, State
+from reslock.pool import LeaseHandle, ResourcePool
+
+__all__ = ["Lease", "LeaseHandle", "PoolStatus", "QueueEntry", "ResourcePool", "State"]

reslock-0.1.0/src/reslock/cleanup.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+
+from reslock.models import State
+
+
+def is_pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def remove_dead_processes(state: State) -> None:
+    state.leases = [lease for lease in state.leases if is_pid_alive(lease.pid)]
+    state.queue = [e for e in state.queue if is_pid_alive(e.pid)]

reslock-0.1.0/src/reslock/cli.py

@@ -0,0 +1,313 @@
+"""CLI for reslock."""
+
+from __future__ import annotations
+
+import re
+import signal
+import subprocess
+import sys
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from reslock.detect import detect_gpu_vram_mb
+from reslock.models import State
+from reslock.pool import ResourcePool
+from reslock.state import DEFAULT_STATE_PATH, ensure_state_file, transact
+
+console = Console()
+
+
+def _parse_size(value: str) -> int:
+    """Parse a size string like '4G', '500M', or plain number (MB)."""
+    m = re.match(r"^(\d+(?:\.\d+)?)\s*([gGmM]?)$", value)
+    if not m:
+        raise click.BadParameter(f"Invalid size: {value}")
+    num = float(m.group(1))
+    unit = m.group(2).upper()
+    if unit == "G":
+        return int(num * 1024)
+    return int(num)
+
+
+@click.group()
+@click.version_option(package_name="reslock")
+def main() -> None:
+    """Resource lock manager for coordinating shared system resources."""
+
+
+@main.command()
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def init(state: Path | None) -> None:
+    """Initialize reslock state file, auto-detecting GPU if available."""
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+
+    gpu = detect_gpu_vram_mb()
+
+    def _init(st: State) -> None:
+        for key, val in gpu.items():
+            if key not in st.resources:
+                st.resources[key] = val
+
+    transact(path, _init)
+
+    if gpu:
+        console.print(f"[green]Detected:[/green] vram_mb={gpu.get('vram_mb', 0)}")
+    console.print(f"[green]State file:[/green] {path}")
+
+
+@main.command(name="set")
+@click.argument("resource")
+@click.argument("value", type=int)
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def set_resource(resource: str, value: int, state: Path | None) -> None:
+    """Set a resource capacity (e.g., reslock set vram_mb 24000)."""
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+
+    def _set(st: State) -> None:
+        st.resources[resource] = value
+
+    transact(path, _set)
+    console.print(f"[green]Set[/green] {resource} = {value}")
+
+
+@main.command()
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def status(state: Path | None) -> None:
+    """Show current resource status, leases, and queue."""
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+    pool = ResourcePool(path)
+    st = pool.status()
+
+    if st.resources:
+        table = Table(title="Resources")
+        table.add_column("Resource", style="cyan")
+        table.add_column("Total", justify="right")
+        table.add_column("Used", justify="right")
+        table.add_column("Free", justify="right")
+        for key, total in st.resources.items():
+            free = st.available.get(key, 0)
+            used = total - free
+            table.add_row(key, str(total), str(used), str(free))
+        console.print(table)
+    else:
+        console.print("[dim]No resources configured. Run 'reslock init' or 'reslock set'.[/dim]")
+
+    if st.leases:
+        table = Table(title=f"Leases ({len(st.leases)} active)")
+        table.add_column("ID", style="cyan")
+        table.add_column("PID")
+        table.add_column("Resources")
+        table.add_column("Priority", justify="right")
+        table.add_column("Label")
+        table.add_column("Flags")
+        table.add_column("Age")
+        now = datetime.now(timezone.utc)
+        for lease in st.leases:
+            age = now - lease.acquired_at
+            mins = int(age.total_seconds()) // 60
+            age_str = f"{mins}m ago" if mins > 0 else f"{int(age.total_seconds())}s ago"
+            res_str = ", ".join(f"{k}={v}" for k, v in lease.resources.items())
+            flags: list[str] = []
+            if lease.reclaimable:
+                flags.append("reclaimable")
+            if lease.reclaim_requested:
+                flags.append("reclaim_requested")
+            table.add_row(
+                lease.id,
+                str(lease.pid),
+                res_str,
+                str(lease.priority),
+                lease.label or "",
+                " ".join(flags),
+                age_str,
+            )
+        console.print(table)
+
+    if st.queue:
+        table = Table(title=f"Queue ({len(st.queue)} waiting)")
+        table.add_column("ID", style="cyan")
+        table.add_column("PID")
+        table.add_column("Resources")
+        table.add_column("Priority", justify="right")
+        table.add_column("Label")
+        table.add_column("Queued")
+        now = datetime.now(timezone.utc)
+        for e in st.queue:
+            age = now - e.queued_at
+            secs = int(age.total_seconds())
+            queued_str = f"{secs // 60}m ago" if secs >= 60 else f"{secs}s ago"
+            res_str = ", ".join(f"{k}={v}" for k, v in e.resources.items())
+            table.add_row(e.id, str(e.pid), res_str, str(e.priority), e.label or "", queued_str)
+        console.print(table)
+
+    if not st.leases and not st.queue:
+        console.print("[dim]No active leases or queued requests.[/dim]")
+
+
+@main.command()
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def list_(state: Path | None) -> None:
+    """List active leases."""
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+    pool = ResourcePool(path)
+    st = pool.status()
+    if not st.leases:
+        console.print("[dim]No active leases.[/dim]")
+        return
+    for lease in st.leases:
+        res_str = ", ".join(f"{k}={v}" for k, v in lease.resources.items())
+        lbl = f"  label={lease.label}" if lease.label else ""
+        console.print(f"  {lease.id}  pid={lease.pid}  {res_str}  prio={lease.priority}{lbl}")
+
+
+# Register "list" as the CLI command name
+list_.__name__ = "list"
+main.add_command(list_, "list")
+
+
+@main.command()
+@click.argument("lease_id", required=False)
+@click.option("--label", "-l", default=None, help="Release by label")
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def release(lease_id: str | None, label: str | None, state: Path | None) -> None:
+    """Release a lease by ID or label."""
+    if not lease_id and not label:
+        raise click.UsageError("Provide a lease ID or --label")
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+    released: list[str] = []
+
+    def _release(st: State) -> None:
+        before = len(st.leases)
+        if lease_id:
+            st.leases = [ls for ls in st.leases if ls.id != lease_id]
+        elif label:
+            st.leases = [ls for ls in st.leases if ls.label != label]
+        released.extend(["x"] * (before - len(st.leases)))
+
+    transact(path, _release)
+    if released:
+        console.print(f"[green]Released {len(released)} lease(s).[/green]")
+    else:
+        console.print("[yellow]No matching lease found.[/yellow]")
+
+
+@main.command()
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+def reset(state: Path | None) -> None:
+    """Clear all state (leases, queue)."""
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+
+    def _reset(st: State) -> None:
+        st.leases.clear()
+        st.queue.clear()
+
+    transact(path, _reset)
+    console.print("[green]State cleared.[/green]")
+
+
+@main.command()
+def schema() -> None:
+    """Print the JSON schema for the state file."""
+    import json
+
+    click.echo(json.dumps(State.model_json_schema(), indent=2))
+
+
+@main.command()
+@click.option("--vram", default=None, help="VRAM to reserve (e.g., 4G, 500M)")
+@click.option("--ram", default=None, help="RAM to reserve (e.g., 16G)")
+@click.option("--cpu", type=int, default=None, help="CPU cores to reserve")
+@click.option("--priority", "-p", type=int, default=0, help="Priority (higher = more urgent)")
+@click.option("--label", "-l", default=None, help="Label for this lease")
+@click.option(
+    "--reclaimable", is_flag=True, help="Allow lease to be reclaimed by higher-priority requests"
+)
+@click.option(
+    "--reclaim-signal",
+    default="SIGTERM",
+    help="Signal to send to the child process when reclaim is requested (default: SIGTERM)",
+)
+@click.option("--state", "-s", type=click.Path(path_type=Path), default=None)
+@click.argument("command", nargs=-1, required=True)
+def run(
+    vram: str | None,
+    ram: str | None,
+    cpu: int | None,
+    priority: int,
+    label: str | None,
+    reclaimable: bool,
+    reclaim_signal: str,
+    state: Path | None,
+    command: tuple[str, ...],
+) -> None:
+    """Reserve resources and run a command.
+
+    With --reclaimable, the lease can be reclaimed by higher-priority requests.
+    When reclaim is requested, the specified signal is sent to the child process.
+    """
+    resources: dict[str, int] = {}
+    if vram:
+        resources["vram_mb"] = _parse_size(vram)
+    if ram:
+        resources["ram_mb"] = _parse_size(ram)
+    if cpu:
+        resources["cpu_cores"] = cpu
+
+    if not resources:
+        raise click.UsageError("Specify at least one resource (--vram, --ram, --cpu)")
+
+    sig = getattr(signal, reclaim_signal, None)
+    if sig is None:
+        raise click.BadParameter(f"Unknown signal: {reclaim_signal}")
+
+    path = state or DEFAULT_STATE_PATH
+    ensure_state_file(path)
+    pool = ResourcePool(path)
+
+    console.print(f"[dim]Waiting for resources: {resources}...[/dim]")
+    with pool.acquire(
+        priority=priority, label=label, reclaimable=reclaimable, **resources
+    ) as lease:
+        console.print(f"[green]Acquired lease {lease.id}[/green]")
+        proc = subprocess.Popen(list(command))
+
+        def _sighandler(signum: int, _frame: object) -> None:
+            proc.send_signal(signum)
+
+        signal.signal(signal.SIGTERM, _sighandler)
+        signal.signal(signal.SIGINT, _sighandler)
+
+        if reclaimable:
+
+            def _watch_reclaim() -> None:
+                while proc.poll() is None:
+                    if lease.reclaim_requested:
+                        console.print(
+                            f"[yellow]Reclaim requested, sending {reclaim_signal} to child[/yellow]"
+                        )
+                        proc.send_signal(sig)
+                        return
+                    time.sleep(0.5)
+
+            threading.Thread(target=_watch_reclaim, daemon=True).start()
+
+        returncode = proc.wait()
+
+    console.print(f"[dim]Lease released. Process exited with code {returncode}.[/dim]")
+    sys.exit(returncode)
+
+
+if __name__ == "__main__":
+    main()

reslock-0.1.0/src/reslock/detect.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+def detect_gpu_vram_mb() -> dict[str, int]:
+    """Detect total GPU VRAM via nvidia-smi. Returns empty dict if not available."""
+    if not shutil.which("nvidia-smi"):
+        return {}
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return {}
+        total = 0
+        for line in result.stdout.strip().splitlines():
+            total += int(line.strip())
+        if total > 0:
+            return {"vram_mb": total}
+    except (subprocess.TimeoutExpired, ValueError, OSError):
+        pass
+    return {}

reslock-0.1.0/src/reslock/models.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_id() -> str:
+    return uuid4().hex[:12]
+
+
+class Lease(BaseModel):
+    id: str = Field(default_factory=_new_id)
+    pid: int
+    resources: dict[str, int]
+    priority: int = 0
+    acquired_at: datetime = Field(default_factory=_utcnow)
+    estimated_seconds: int | None = None
+    reclaimable: bool = False
+    reclaim_requested: bool = False
+    label: str | None = None
+
+    model_config = {"extra": "forbid"}
+
+
+class QueueEntry(BaseModel):
+    id: str = Field(default_factory=_new_id)
+    pid: int
+    resources: dict[str, int]
+    priority: int = 0
+    queued_at: datetime = Field(default_factory=_utcnow)
+    label: str | None = None
+
+    model_config = {"extra": "forbid"}
+
+
+class State(BaseModel):
+    version: int = 1
+    resources: dict[str, int] = Field(default_factory=dict)
+    leases: list[Lease] = Field(default_factory=list)
+    queue: list[QueueEntry] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+    def available(self) -> dict[str, int]:
+        used: dict[str, int] = {}
+        for lease in self.leases:
+            for key, val in lease.resources.items():
+                used[key] = used.get(key, 0) + val
+        return {key: total - used.get(key, 0) for key, total in self.resources.items()}
+
+    def can_fit(self, resources: dict[str, int]) -> bool:
+        avail = self.available()
+        return all(avail.get(key, 0) >= val for key, val in resources.items())
+
+    def reclaimable_for(self, resources: dict[str, int]) -> list[Lease]:
+        """Return reclaimable leases that would need to be reclaimed to fit the request."""
+        avail = self.available()
+        shortfall: dict[str, int] = {}
+        for key, val in resources.items():
+            deficit = val - avail.get(key, 0)
+            if deficit > 0:
+                shortfall[key] = deficit
+        if not shortfall:
+            return []
+        candidates = [ls for ls in self.leases if ls.reclaimable and not ls.reclaim_requested]
+        candidates.sort(key=lambda ls: ls.priority)
+        result: list[Lease] = []
+        remaining = dict(shortfall)
+        for lease in candidates:
+            if not remaining:
+                break
+            helps = False
+            for key in list(remaining):
+                contrib = lease.resources.get(key, 0)
+                if contrib > 0:
+                    helps = True
+                    remaining[key] -= contrib
+                    if remaining[key] <= 0:
+                        del remaining[key]
+            if helps:
+                result.append(lease)
+        if remaining:
+            return []
+        return result
+
+
+class PoolStatus(BaseModel):
+    resources: dict[str, int]
+    available: dict[str, int]
+    leases: list[Lease]
+    queue: list[QueueEntry]

reslock-0.1.0/src/reslock/pool.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from reslock.models import Lease, PoolStatus, QueueEntry, State
+from reslock.state import DEFAULT_STATE_PATH, ensure_state_file, read_state, transact
+
+
+class LeaseHandle:
+    """Handle for an acquired lease, used to update or release it."""
+
+    def __init__(self, lease: Lease, pool: ResourcePool) -> None:
+        self._lease = lease
+        self._pool = pool
+        self._released = False
+
+    @property
+    def id(self) -> str:
+        return self._lease.id
+
+    @property
+    def reclaim_requested(self) -> bool:
+        """Check the state file for whether reclaim has been requested."""
+        state = read_state(self._pool._path)
+        for lease in state.leases:
+            if lease.id == self._lease.id:
+                self._lease = lease
+                return lease.reclaim_requested
+        return True  # lease gone = treat as reclaimed
+
+    def wait_for_reclaim(self, poll_interval: float = 0.5) -> None:
+        """Block until reclaim is requested for this lease."""
+        while not self.reclaim_requested:
+            time.sleep(poll_interval)
+
+    async def wait_for_reclaim_async(self, poll_interval: float = 0.5) -> None:
+        """Async wait until reclaim is requested for this lease."""
+        while not self.reclaim_requested:
+            await asyncio.sleep(poll_interval)
+
+    def update(self, estimated_seconds: int | None = None) -> None:
+        def _update(state: State) -> None:
+            for lease in state.leases:
+                if lease.id == self._lease.id:
+                    if estimated_seconds is not None:
+                        lease.estimated_seconds = estimated_seconds
+                    break
+
+        transact(self._pool._path, _update)
+
+    def release(self) -> None:
+        if self._released:
+            return
+        self._released = True
+
+        def _release(state: State) -> None:
+            state.leases = [ls for ls in state.leases if ls.id != self._lease.id]
+
+        transact(self._pool._path, _release)
+
+
+class ResourcePool:
+    def __init__(self, path: str | Path | None = None) -> None:
+        self._path = Path(path) if path else DEFAULT_STATE_PATH
+        ensure_state_file(self._path)
+
+    @contextmanager
+    def acquire(
+        self,
+        *,
+        priority: int = 0,
+        estimated_seconds: int | None = None,
+        reclaimable: bool = False,
+        label: str | None = None,
+        poll_interval: float = 0.25,
+        **resources: int,
+    ) -> Generator[LeaseHandle, None, None]:
+        handle = self._acquire_blocking(
+            resources=resources,
+            priority=priority,
+            estimated_seconds=estimated_seconds,
+            reclaimable=reclaimable,
+            label=label,
+            poll_interval=poll_interval,
+        )
+        try:
+            yield handle
+        finally:
+            handle.release()
+
+    async def acquire_async(
+        self,
+        *,
+        priority: int = 0,
+        estimated_seconds: int | None = None,
+        reclaimable: bool = False,
+        label: str | None = None,
+        poll_interval: float = 0.25,
+        **resources: int,
+    ) -> LeaseHandle:
+        queue_id: str | None = None
+        pid = os.getpid()
+
+        def _enqueue(state: State) -> str:
+            entry = QueueEntry(pid=pid, resources=resources, priority=priority, label=label)
+            state.queue.append(entry)
+            return entry.id
+
+        queue_id = transact(self._path, _enqueue)
+
+        try:
+            while True:
+                handle = self._try_promote(
+                    queue_id, resources, priority, estimated_seconds, reclaimable, label
+                )
+                if handle is not None:
+                    return handle
+                await asyncio.sleep(poll_interval)
+        except BaseException:
+            self._remove_from_queue(queue_id)
+            raise
+
+    def try_acquire(
+        self,
+        *,
+        priority: int = 0,
+        estimated_seconds: int | None = None,
+        reclaimable: bool = False,
+        label: str | None = None,
+        **resources: int,
+    ) -> LeaseHandle | None:
+        pid = os.getpid()
+        result: list[LeaseHandle] = []
+
+        def _try(state: State) -> None:
+            if not state.can_fit(resources):
+                return
+            lease = Lease(
+                pid=pid,
+                resources=resources,
+                priority=priority,
+                estimated_seconds=estimated_seconds,
+                reclaimable=reclaimable,
+                label=label,
+            )
+            state.leases.append(lease)
+            result.append(LeaseHandle(lease, self))
+
+        transact(self._path, _try)
+        return result[0] if result else None
+
+    def status(self) -> PoolStatus:
+        state = read_state(self._path)
+        return PoolStatus(
+            resources=state.resources,
+            available=state.available(),
+            leases=state.leases,
+            queue=state.queue,
+        )
+
+    def _acquire_blocking(
+        self,
+        resources: dict[str, int],
+        priority: int,
+        estimated_seconds: int | None,
+        reclaimable: bool,
+        label: str | None,
+        poll_interval: float,
+    ) -> LeaseHandle:
+        pid = os.getpid()
+
+        def _enqueue(state: State) -> str:
+            entry = QueueEntry(pid=pid, resources=resources, priority=priority, label=label)
+            state.queue.append(entry)
+            return entry.id
+
+        queue_id = transact(self._path, _enqueue)
+
+        try:
+            while True:
+                handle = self._try_promote(
+                    queue_id, resources, priority, estimated_seconds, reclaimable, label
+                )
+                if handle is not None:
+                    return handle
+                time.sleep(poll_interval)
+        except BaseException:
+            self._remove_from_queue(queue_id)
+            raise
+
+    def _try_promote(
+        self,
+        queue_id: str,
+        resources: dict[str, int],
+        priority: int,
+        estimated_seconds: int | None,
+        reclaimable: bool,
+        label: str | None,
+    ) -> LeaseHandle | None:
+        pid = os.getpid()
+        result: list[LeaseHandle] = []
+
+        def _promote(state: State) -> None:
+            # Check if we're still in queue
+            in_queue = any(e.id == queue_id for e in state.queue)
+            if not in_queue:
+                return
+
+            # Check if higher-priority waiters should go first
+            for entry in state.queue:
+                if entry.id == queue_id:
+                    break
+                if entry.priority > priority and state.can_fit(entry.resources):
+                    return  # higher priority waiter can fit, let them go first
+
+            if state.can_fit(resources):
+                lease = Lease(
+                    pid=pid,
+                    resources=resources,
+                    priority=priority,
+                    estimated_seconds=estimated_seconds,
+                    reclaimable=reclaimable,
+                    label=label,
+                )
+                state.leases.append(lease)
+                state.queue = [e for e in state.queue if e.id != queue_id]
+                result.append(LeaseHandle(lease, self))
+            else:
+                # Try reclaiming
+                to_reclaim = state.reclaimable_for(resources)
+                if to_reclaim:
+                    for lease in to_reclaim:
+                        lease.reclaim_requested = True
+
+        transact(self._path, _promote)
+        return result[0] if result else None
+
+    def _remove_from_queue(self, queue_id: str) -> None:
+        def _remove(state: State) -> None:
+            state.queue = [e for e in state.queue if e.id != queue_id]
+
+        transact(self._path, _remove)

reslock-0.1.0/src/reslock/state.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import TypeVar
+
+import portalocker
+
+from reslock.cleanup import remove_dead_processes
+from reslock.models import State
+
+T = TypeVar("T")
+
+DEFAULT_STATE_PATH = Path.home() / ".reslock" / "state.json"
+
+
+def ensure_state_file(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(State().model_dump_json(indent=2))
+
+
+def read_state(path: Path) -> State:
+    with portalocker.Lock(str(path), "r", timeout=5) as fh:
+        data = fh.read()
+    return State.model_validate_json(data)
+
+
+def write_state(path: Path, state: State) -> None:
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(state.model_dump_json(indent=2))
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def transact(path: Path, fn: Callable[[State], T]) -> T:
+    """Atomically read, modify, and write the state file under an exclusive lock.
+
+    The callable `fn` receives the current state (with dead processes cleaned up)
+    and may mutate it. The modified state is written back. The return value of `fn`
+    is returned to the caller.
+    """
+    with portalocker.Lock(str(path), "r+", timeout=5) as fh:
+        data = fh.read()
+        state = State.model_validate_json(data)
+        remove_dead_processes(state)
+        result = fn(state)
+        new_data = state.model_dump_json(indent=2)
+        fh.seek(0)
+        fh.truncate()
+        fh.write(new_data)
+    return result