Skip to content

Async Frameworks

An ASGI application runs endpoint code on an event loop. Horsies has a sync form and an async form of each producer call. On such a loop, use the async form.

Read this page when a web framework (FastAPI, Starlette, or another ASGI framework) sends tasks or starts workflows.

The sync forms block their thread. On a thread that runs an event loop, the block would stop every coroutine on that loop. For this reason the sync forms refuse to run there. See Async Code and Jupyter for the full table of sync calls and their ASYNC_CONTEXT results.

app.get_broker() creates the broker once per process. A configuration error raises at that call, so a call in the lifespan fails the start of the server. The call opens no connection. Connections open on the first database call.

Close the broker at shutdown with close_async(). It returns a BrokerResult. Handle the Err side.

import logging
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException
from horsies import Err, Ok
from instance import app as horsies_app
from tasks import send_welcome_email
logger = logging.getLogger(__name__)
@asynccontextmanager
async def lifespan(_api: FastAPI) -> AsyncIterator[None]:
broker = horsies_app.get_broker()
try:
yield
finally:
match await broker.close_async():
case Ok():
pass
case Err(close_error):
logger.error("broker close failed: %s", close_error.message)
api = FastAPI(lifespan=lifespan)

An async def endpoint uses send_async(), start_async() and get_async().

@api.post("/welcome/{address}")
async def welcome(address: str) -> dict[str, str]:
match await send_welcome_email.send_async(address=address):
case Ok(handle):
return {"task_id": handle.task_id}
case Err(send_error):
raise HTTPException(status_code=503, detail=send_error.code.value)

A sync call in this endpoint returns Err with ASYNC_CONTEXT. Nothing is enqueued. The error keeps the payload, so retry_send_async() can send it.

Use the Sync Forms Only in Plain def Endpoints

Section titled “Use the Sync Forms Only in Plain def Endpoints”

FastAPI runs a plain def endpoint in a thread pool. That thread has no event loop, so the sync form is allowed. A sync send without an idempotency key writes on the endpoint’s thread, through the sync send pool of the broker. The first send of the broker, a send with an idempotency key, and the other sync calls, for example TaskHandle.get(), run on the broker’s own runner loop.

@api.post("/welcome-blocking/{address}")
def welcome_blocking(address: str) -> dict[str, str]:
match send_welcome_email.send(address=address):
case Ok(handle):
return {"task_id": handle.task_id}
case Err(send_error):
raise HTTPException(status_code=503, detail=send_error.code.value)

Prefer one form per application. The async form opens connections in the set of the server’s event loop. The sync form opens them in the set of the runner loop and in the sync send pool. A mix of both forms can open all three. See Connection Ceiling.

A broker keeps one resource set (pools and a listener) for each event loop that calls it. It serves at most 5 open caller loops, plus its own sync runner loop and, in a worker child, the task loop (MAX_CALLER_EVENT_LOOPS = 5).

A call from one more open loop returns EVENT_LOOP_LIMIT in the error type of that call. Nothing runs. The error clears when one of the open loops closes.

An ASGI server such as uvicorn runs one loop for each process, so a server stays far below the limit. The limit matters for code that creates loops itself, and for test runs. See Event Loops.

Don’t call sync close() in a coroutine. It returns ASYNC_CONTEXT and closes nothing.

# Wrong
broker.close()
# Correct
await broker.close_async()

Don’t create an event loop for each call. Each open loop keeps its resource set. The sixth open loop gets EVENT_LOOP_LIMIT.

# Wrong: each call leaves one more open loop
loop = asyncio.new_event_loop()
loop.run_until_complete(horsies_app.get_broker().ping_database_async())
# Correct: asyncio.run() closes its loop
asyncio.run(horsies_app.get_broker().ping_database_async())