nx_async_rt.nx
buildroot/runtime/nx_async_rt.nx
about
async_rt.nx -- cooperative async task runtime.
Phase A: runtime data structures + scheduler. Language-level
`async fn` / `await` (EFFICIENCY_ROADMAP ยง4.3) is a parser
change pending; this module gives callers enough machinery
to hand-code stackful coroutines today + get lifted into real
async/await syntax later without breaking the API.
Design: single-threaded cooperative scheduler on one kernel
thread. Each task = (function_pointer, state_blob).
Scheduler runs ready queue to exhaustion, then epolls for IO
readiness + wakes blocked tasks.
Why single-threaded: thread safety without atomics. Multi-
thread scheduling adds complexity that belongs in a later
phase once the sequential model is proven.
Used by: HTTP server accept loops, DNS resolver, file watcher,
anything that would otherwise thread-per-connection.
Invariants:
AR1 Scheduler `run_until_idle` returns when all tasks are
blocked waiting for IO + nothing's ready. Caller
does the epoll_wait before re-entering.
AR2 `task_spawn` always succeeds if slot cap not hit;
returns task id.
AR3 `task_yield` marks the calling task ready + saves its
state via the caller-supplied resume hook.
dependencies 1 imports · 0 importers
imports: nx_syscalls.nx
imported by: nobody (leaf or entry point)
call flow from main pre-order; caps 40 nodes / depth 6 declared; ↻ = already shown
structs
| 46 | struct AsyncTask |
| 55 | struct Runtime |
consts
| 38 | const AR_MAX_TASKS: i64 = 256 |
| 39 | const AR_ERR_FULL: i64 = -1 |
| 40 | const AR_ERR_NO_SUCH: i64 = -2 |
| 42 | const TASK_READY: i64 = 0 |
| 43 | const TASK_BLOCKED: i64 = 1 |
| 44 | const TASK_DONE: i64 = 2 |
functions
| 61 | func rt_new() -> *Runtime |
| 72 | func task_spawn(rt: *Runtime, resume_fn: i64, state_blob: i64) -> i64 called by 1: main |
| 88 | func task_find(rt: *Runtime, id: i64) -> i64 |
| 100 | func task_wake(rt: *Runtime, id: i64) -> i64 |
| 112 | func task_block(rt: *Runtime, id: i64, fd: i64, events: i64) -> i64 |
| 124 | func task_complete(rt: *Runtime, id: i64) -> i64 |
| 134 | func rt_count_state(rt: *Runtime, state: i64) -> i64 called by 1: main |
| 147 | func main() -> i64 |