gui-async-hygiene

name	gui-async-hygiene
description	What may and may not run on the GUI server's event loop, and how to offload the rest. Use when adding or editing anything under src/lerobot/gui — an endpoint, a background task, a Hub call, a subprocess — or when the GUI freezes.

GUI async hygiene

The GUI is one asyncio process. A synchronous call that blocks inside an async def stops everything — static files, websockets, SSE, other operators' requests — for as long as it takes. This is not theoretical: a blackholed Hub made the whole GUI unusable until kernel TCP timeouts fired, because whoami() was awaited inline.

The rules

1. Nothing that can block runs on the loop. Network calls, subprocesses, large file reads, parquet rewrites, model loads. Offload them.

2. Never the shared default executor. run_in_executor(None, …) and asyncio.to_thread(…) share one small pool with video decode, camera teardown and FastAPI's own sync handlers, so a stalled Hub probe starves work with nothing to do with it. Give each class of work its own bounded pool:

_image_status_executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="gui-image-status")

Precedent: _decode_executor and _prefetch_executor in api/datasets.py.

3. The timeout belongs in the client, not the awaiter. Cancelling asyncio.wait_for(asyncio.to_thread(f)) abandons the await; f keeps running and keeps its slot in the pool, so repeated requests leak it. Only HfApi(timeout=…), requests(…, timeout=…), subprocess.run(…, timeout=…) actually bound the work.

4. A passive GET performs no network I/O. It returns cached state plus its freshness; refreshing is a background task or an explicit POST. image-status is the worked example: the git fetch moved behind POST /training/image-status/refresh, the probe runs in a named pool, and the result is cached for 30s.

5. Transfers go through the subprocess worker. hub_worker.py owns uploads and downloads end to end. The server never calls huggingface_hub transfer helpers directly.

The trap that keeps catching people

Blocking hides behind things that do not look like I/O. The freeze above was return get_auth_status() — one level down, whoami(). Later, LeRobotDataset(repo_id) inside an async handler resolved against the Hub with no call in sight that looks like network. A constructor.

So when reviewing an async handler, do not scan for requests and subprocess. Ask of every call: could this reach a syscall that waits on something outside this process? If you cannot answer without opening the callee, open the callee.

What the lint does and does not cover

scripts/lint/no_blocking_in_async.py runs in pre-commit as a ratchet against a baseline. Read its output correctly:

• The shared-pool rule is sound. run_in_executor(None, …) is a literal in the AST and cannot be disguised.
• The blocking-call rules are a heuristic over a denylist of names. They find what someone thought to list and miss everything else — they missed the LeRobotDataset case entirely.

A clean run means "none of the known shapes are present", never "this cannot block". Real coverage needs a runtime detector measuring the symptom rather than enumerating causes; tracked as a [High] item in src/lerobot/gui/TODO.md.

Silence a justified case with # blocking-ok: <reason> (startup paths that run before the loop serves traffic, work already on a bounded pool) rather than widening the baseline.