🇬🇧 English version

Praktyczna demonstracja trzech pułapek, w które wpada niemal każdy backend na FastAPI:

1. Event Loop Trap — synchroniczny kod w async def blokuje cały serwer.
2. ThreadPoolExecutor — poprawne odciążenie event loopa, ale…
3. GIL Lock — CPU-bound Python w wątkach nie skaluje się na rdzenie.

Projekt używa Python 3.14t (free-threaded), żebyś mógł porównać zachowanie z GIL-em i bez niego.

Tip: Aby zainstalować free-threaded Python przez uv:

uv python install 3.14t

# Klonowanie i setup
git clone <repo-url> && cd event-loop-trap-gil-off
uv sync

# Uruchomienie serwera
uv run uvicorn app.main:app --reload

Serwer startuje na http://127.0.0.1:8000.

Health check. Zawsze odpowiada natychmiast — używaj go do sprawdzania, czy event loop jest wolny.

Pułapka nr 1. async def + time.sleep(5) — blokuje event loop na 5 sekund. W tym czasie /ping też nie odpowiada.

# Terminal 1 — odpal ciężki request
curl http://127.0.0.1:8000/heavy-blocking

# Terminal 2 — spróbuj ping w trakcie (czeka!)
curl http://127.0.0.1:8000/ping

Prawidłowe rozwiązanie. Synchroniczna praca leci na ThreadPoolExecutor, event loop pozostaje wolny.

# Terminal 1
curl http://127.0.0.1:8000/heavy-good

# Terminal 2 — ping odpowiada natychmiast
curl http://127.0.0.1:8000/ping

Pułapka nr 2 — GIL. Pure-Python CPU burn w ThreadPoolExecutor. Z GIL-em 8 równoległych requestów trwa tyle co 8 sekwencyjnych. Bez GIL-a (Python 3.14t) — skaluje się na rdzenie.

Skrypt scripts/cpu_bench.py automatyzuje pomiar:

uv run python scripts/cpu_bench.py --concurrency 8 --iterations 10_000_000

Wyświetla tabelę z czasami per wątek, a na końcu kluczowe metryki:

event-loop-trap-gil-off/
├── app/
│   ├── main.py            # FastAPI — endpointy i lifespan
│   └── agent_service.py   # ThreadPoolExecutor + CPU burn logic
├── scripts/
│   └── cpu_bench.py        # Klient benchmarkowy (httpx + rich)
├── pyproject.toml
└── uv.lock

Centralna klasa zarządzająca pulą wątków (ThreadPoolExecutor):

• ainvoke_graph(query) — async wrapper wrzucający synchroniczną pracę na pulę wątków przez loop.run_in_executor().
• acpu_burn(iterations) — symulacja CPU-bound workloadu (pure-Python pętla i * i).
• shutdown() — graceful shutdown puli przy zamykaniu aplikacji.

async def + blokujący kod = zablokowany serwer. Rozwiązanie: loop.run_in_executor() lub def (sync) zamiast async def — wtedy FastAPI sam wrzuci to na thread pool.

ThreadPoolExecutor naprawia responsywność (event loop nie stoi), ale nie naprawia równoległości CPU. Z GIL-em wątki CPU-bound wykonują się szeregowo — jeden GIL na cały proces.

Python 3.14t wyłącza GIL. Wątki CPU-bound naprawdę działają równolegle. Ten sam kod, ta sama architektura — ale parallel speedup rośnie proporcjonalnie do liczby rdzeni.

• FastAPI — framework ASGI
• Uvicorn — serwer ASGI
• httpx — async HTTP client (benchmark)
• Rich — formatowanie tabel w terminalu
• uv — zarządzanie zależnościami i środowiskiem

MIT