perf: freeze the heap in production backend workers once the app is built
Merged
BE
1d ago+69+69+01234567890123456789-4-4-0123456789
Summary
- Every backend worker loads
_backend_app. Inprodmode it now runsgc.collect(); gc.freeze()once the app is built. The app lives as long as the worker, so full collections stop walking it. - #7079 freezes the supervisor's heap before granian forks. That covers what importing the app creates, but not workers that build the app themselves:
- spawned granian workers: the default on macOS and Windows, with
REFLEX_BACKEND_START_METHOD=spawn, and the fallback when a telemetry send outlives the drain - uvicorn workers on Windows
- gunicorn, whose master builds the app with
--preloadand forks without freezing
- spawned granian workers: the default on macOS and Windows, with
- Forked granian workers also left whatever
app()builds after the fork unfrozen. - The collection runs first, so the build's garbage is freed instead of frozen with it. Dev and preview workers are replaced on every reload, so they skip both.
Measurement
The test app was generated: 400 states, each with 10 fields and 10 computed vars, plus 400 pages. It ran with reflex run --env prod --backend-only on Python 3.14. A lifespan task in each worker counted the unfrozen objects and timed one gc.collect():
| Launch path | Unfrozen objects (before → after) | gc.collect() (before → after) |
|---|---|---|
| granian, fork (Linux default) | 13.9k → 332 | 23 → 20 ms |
| granian, spawn | 276k → 332 | 91 → 20 ms |
gunicorn --preload | 282k → 3.4k | 84 → 21 ms |
A full collection's cost grows with the unfrozen heap, so on larger apps the spawn and gunicorn rows become long pauses. For scale, the same app with its pages compiled in the worker leaves 1.43M unfrozen objects:
- A full collection then takes about 580 ms on 3.14 and 665 ms on 3.13.
- Frozen, the longest automatic full collection under a request-like allocation load drops to 31 ms on 3.14 and 47 ms on 3.13.
Costs
- Startup: each worker runs one collection when it starts. After a fork that takes milliseconds, because the supervisor already froze the import. A worker that built everything itself pays one full collection.
- Cycles created after the freeze: if an object frozen here later becomes unreachable through a reference cycle, it is never collected. Reference counting still frees everything else. The build's own garbage is collected before the freeze, so what stays frozen is the app itself.
Test plan
-
test_backend_worker_freezes_the_built_app_in_prodruns the worker factory in a fresh interpreter with automatic collection off. In prod the built app ends up frozen and the build's cyclic garbage is freed; in dev neither happens. The prod case fails without the change. -
uv run pytest tests/units -
ruff check,ruff format --check,pyright - Manual: the table above, with granian (fork and spawn) and gunicorn.
🤖 Generated with Claude Code