Async Frameworks
Async Frameworks
Section titled “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.
Why and When
Section titled “Why and When”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.
How To
Section titled “How To”Own the Broker in the Lifespan
Section titled “Own the Broker in the Lifespan”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 loggingfrom collections.abc import AsyncIteratorfrom contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPExceptionfrom horsies import Err, Ok
from instance import app as horsies_appfrom tasks import send_welcome_email
logger = logging.getLogger(__name__)
@asynccontextmanagerasync 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)Call the Async Forms in Coroutines
Section titled “Call the Async Forms in Coroutines”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.
The Event-Loop Limit
Section titled “The Event-Loop Limit”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.
Things to Avoid
Section titled “Things to Avoid”Don’t call sync close() in a coroutine. It returns ASYNC_CONTEXT and closes nothing.
# Wrongbroker.close()
# Correctawait 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 looploop = asyncio.new_event_loop()loop.run_until_complete(horsies_app.get_broker().ping_database_async())
# Correct: asyncio.run() closes its loopasyncio.run(horsies_app.get_broker().ping_database_async())