pyroutine

Goroutine-style concurrency for free-threaded Python 3.14t (GIL disabled).

Pyroutines are greenlet-backed: cheap to spawn (millions), parked without holding an OS thread, and run in true parallel across cores — the same trio of properties that make Go's goroutines special, on a custom M:N runtime.

from pyroutine import spawn, Queue

def worker(q, n):
    q.put(n * n)          # ordinary blocking code — no async/await

q = Queue()               # cooperative FIFO queue (mimics queue.Queue)
task = spawn(worker, q, 10) # launch as a pyroutine task
spawn(worker, q, 5)
print(q.get(), q.get())   # 100, 25
task.join()               # wait for the task to finish

Requirements

Runs on a free-threaded build (python3.14t) with greenlet ≥ 3.5.1:

uv python pin 3.14t      # -> .python-version: 3.14+freethreaded
uv venv --python 3.14t
uv sync
uv run --no-sync python your_script.py

Install

The PyPI distribution name is pyroutine-rt; the import name is pyroutine. (pip install pyroutine / pyroutines grabs unrelated packages — use pyroutine-rt.)

pip install pyroutine-rt        # then:  from pyroutine import spawn, gather
# or with uv:
uv add pyroutine-rt

Install the latest unreleased code straight from git:

pip install "pyroutine-rt @ git+https://github.com/VigyatGoel/pyroutine.git"

Either way, do it inside a free-threaded python3.14t environment (see Requirements); on a stock GIL build it imports but won't run pyroutines in parallel.

Benchmarks

Cross-library benchmark suite in benchmarks/ comparing pyroutine against asyncio/threading/multiprocessing and FastAPI/Flask/aiohttp/httpx/requests across four surfaces: concurrency model, HTTP server, HTTP client, spawn/memory scaling.

uv sync --group bench        # competitor libs
brew install oha             # external HTTP load tool (server suite)
uv run --no-sync python -m benchmarks.run_all

Results print and write to benchmarks/RESULTS.md + results.json. The server suite skips with a hint if oha is absent. This dev box is 4 perf + 4 efficiency cores, so CPU-parallel speedup caps ~4x.

API (v1)

See examples/: fanout.py, pipeline.py, echo_server.py, http_server_example.py.

How it works

Greenlets give cheap stackful parking — a pyroutine can suspend anywhere, mid-stack, holding no OS thread (~1 KB each). One hard greenlet constraint shapes everything: a greenlet can't be switched from a different OS thread than the one that created it (greenlets don't migrate). So the runtime is N independent per-core cooperative schedulers running in parallel:

• Worker (M) — one OS thread per processor (default os.cpu_count()). Its main greenlet is a hub: a loop that runs ready pyroutines and, when one parks, switches to the next.
• Pyroutine (G) — a greenlet, bound for life to the worker that started it.
• Pending queues — per-worker queues of not-yet-started pyroutines, assigned round-robin, with work-stealing (the only thing that can cross threads is a not-yet-started task).
• Park / wake — a parked pyroutine yields to its hub; waking it (possibly from another worker or the main thread) enqueues its greenlet on its owner worker's ready queue and signals that worker. Values and wakeups cross threads, greenlets don't.
• Netpoller — a single selectors (kqueue/epoll) thread. Socket I/O that would block parks the pyroutine and registers the fd; when it's ready the poller wakes the pyroutine. Thousands–millions of connections wait here on one thread, holding no workers — pyroutine's analogue of Go's integrated network poller.

Cooperative caveat (the one trade-off)

Only cooperative operations park cheaply: Queue operations, sleep(), yield_(), and socket I/O via Socket (which parks on the netpoller). Those scale to millions of parked pyroutines.

A blocking call the runtime doesn't know about — time.sleep, file I/O, DNS, or a library using raw blocking sockets like requests — would freeze its worker and every pyroutine on it. Wrap those in run_blocking, which offloads to a helper thread pool:

import requests
from pyroutine import spawn, run_blocking

def fetch(url):
    return run_blocking(requests.get, url).status_code   # one pool thread per call

task = spawn(fetch, "https://httpbin.org/get")
status_code = task.result()

So native socket concurrency (via Socket) is cheap and unbounded; unwrapped third-party blocking I/O is bounded by OS threads (~thousands). A gevent-style monkeypatch to make requests use the netpoller transparently is on the roadmap.

Compared to Go

Roadmap

gevent-style socket monkeypatching so plain requests/socket code uses the netpoller without run_blocking; select (with non-blocking default); Context (cancellation/deadline); timers/ticker.

Development

uv run --no-sync pytest          # full suite (run on python3.14t)