3.30 · Guides
Sync and async execution¶
Hinoki runs on one event loop per worker. Async is the native way; sync is a supported way, not a second-class one: a plain def handler or hook runs on a bounded thread pool (settings.ExecutionSettings.sync_workers, sync_queue; a full queue answers 503 overloaded, in handlers and in sync hooks), the request's context follows it, and the sync ORM methods hand their work back to the worker's loop and block that thread, never the loop.
Naming convention¶
A name with the a prefix awaits the database (aget, acreate, acount); the same name without it is the blocking twin for sync handlers. A query builder is lazy until you evaluate it, and awaiting the queryset itself is the async twin of .list():
posts = await Post.filter(published=True).order_by("-created") # async
posts = Post.filter(published=True).order_by("-created").list() # sync handler
first = await Post.all().afirst()
aall() was removed: await Post.all() replaces await Post.all().aall().
Parity table¶
| Surface | Async | Sync | Notes |
|---|---|---|---|
| Action handlers | async def |
def |
Sync runs on the executor |
Generated CRUD hooks (get_queryset, written_queryset, to_schema, store, change, remove) |
async def |
def |
Sync overrides run on the same bounded executor; use the matching sync or async ORM methods |
Auth providers (authenticate, resolve, resolve_token, JWT resolve_claims) |
async def |
def |
Sync hooks run on the executor, so sync model calls are safe inside them |
| Model: create / get / update / delete | acreate, aget, aget_or_none, aupdate, aupdate_where, adelete, asave, aupdate_from, abulk_create, abulk_update, abulk_delete |
create, get, get_or_none, update, update_where, delete, save, update_from, bulk_create, bulk_update, bulk_delete |
Sync calls only work inside a sync handler or hook served by Hinoki. The sync writes take the same returning=False option as their async twins (models) |
| QuerySet: read | await queryset, afirst, aget, acount, aexists, apaginate |
list, first, get, count, exists, paginate |
|
| QuerySet: write | aupdate, adelete |
update, delete |
|
| Relations | explicit loading (select_related, prefetch_related) |
same | never lazy, so no hidden I/O in either style |
Raw SQL (Database.fetch, fetch_one, execute) |
async | none | Use the model/queryset methods from sync code; raw SQL is an async-only escape hatch |
| Transactions | atomic=True on the action |
same | The runtime owns it for both styles |
| Atomic blocks in application code | async with db.atomic():, @db.atomic on an async def |
with db.atomic():, @db.atomic on a plain def |
The sync forms run on a worker thread served by Hinoki and raise RuntimeError on the event loop; atomic=True on the action covers a whole handler (transactions) |
Schema, Request, Response, parsers, renderers |
plain code | same | No I/O |
| Password hashing | await hasher.hash/verify |
hash_sync, verify_sync |
The async calls use a bounded thread pool |
Error handlers (app.error_handler) |
async def |
def |
Run on the loop: no blocking calls inside |
| Module lifespans | async context manager | none | Resources belong to the worker's loop |
| App startup/shutdown hooks | async def hook(ctx) |
def hook(ctx) on the sync executor |
Listed in Hinoki(on_startup=..., on_shutdown=...) |
Admin hooks (stats, check, save, remove) |
async def |
none | The admin runs on the loop; override with async def |
| Tests | ASGIClient |
SyncClient |
Same behaviour through both |
Dev MCP run_scenario |
n/a | n/a | Runs the app in-process |
Limits to know¶
- Sync hooks use the same pool as sync handlers. Sync auth and CRUD hooks take an executor slot; a flood of bad credentials or long-running hooks can fill the queue and make legitimate sync work answer 503 (
overloaded, withRetry-After). Keep sync hooks short, reject malformed credentials before touching the database, and prefer async hooks when they can use async APIs. - A sync auth hook runs before the action's transaction opens, so it is never part of it.
- Sync model calls only work inside the application's sync handlers and hooks. In a test body use the async API (an async fixture) or your own connection, also with
SyncClient. - No sync lifespan, sync admin hooks, sync background tasks (
ctx.tasks.start_soontakes coroutines) or syncDatabaseSQL. A sync error handler runs on the loop and must not call the ORM (its failure is treated as "unhandled"). SyncClientis available only inside itswithblock and raises a timeout error aftertimeoutseconds.
Rules of thumb¶
- Prefer
asynchandlers; usedeffor code that is naturally blocking (a library without async support, CPU work measured to be short). - Never call blocking code from an
async def; never call ana...coroutine from adefwithoutrun_sync-style helpers (the sync model methods already do that for you). - CPU-heavy work belongs in a separate process or worker, not in either pool.
- A sync call made on the event loop itself raises, with a message naming the
a...variant.
Verified¶
The test suite exercises sync and async handlers, synchronous authentication hooks, ORM calls through both clients, mixed traffic and cancellation against a disposable database. There are no synchronous module lifespans, admin hooks or background task APIs; those surfaces are async-only by design.