Module async/index

Why timeout(...) produced no value (D18).

The old Option(T) return collapsed these two outcomes into each other — and, when T was itself an Option, into a task that legitimately returned .None. A caller that wants to retry on a slow task but give up on a cancelled one could not tell them apart.

Which operand of select finished first, with its result.

Suspend the current async task until the next event-loop turn: drain the ready queue, then poll (and, when idle with pending I/O, block in) I/O.

There is NO TIMER under this. The future is created pending and completed at the top of the next ready-task drain, after that drain has measured its budget, so the resumed continuation lands beyond the budget and runs in the following step — with exactly one __yo_io_poll() in between. That is the same mechanism std/async/waker's yield_now documents, and the two are now the same thing.

It was a 1 ms timer until v0.2.32, for a bootstrap reason and not a design one: yield is on the compiler's OWN import path (through std/fs/watch), and a seed compiler emits the async runtime it was built with — so pointing this at __yo_async_yield_start could not link until a published seed carried that symbol. v0.2.31 is the first that does.

Two earlier shapes are ruled out and neither should come back. A body of return(()) completes the future SYNCHRONOUSLY, so io.await(yield(io), io) never reaches __yo_async_poll_step at all: a poll-until-finished loop built on it (is_finished() + await yield()) spins without ever polling I/O and the polled task never progresses (the build smoke hang's spin component, issues/fixed/build-smoke-hangs-registry-perturbation.md). An ALREADY-COMPLETE future is the same failure by a different route — the await point takes an inline fast path for one of those and the task never leaves the C stack.

Await every handle, in order, resolving to each task's result (.None for a task that was aborted). All tasks run concurrently on the loop — the wait costs the SLOWEST task's wall time, not the sum. It drains the list: each handle is consumed by its join.

results := io.await(join_all(handles, io), io); // ArrayList(Option(T))

Resolve once at least one handle is terminal (completed OR aborted), to its index, and hand the list back: (index, handles). The losers keep running: a JoinHandle dropped without an await DETACHES its task, so abort() the losers if their work is unwanted (race_first does that for you). Panics on an empty list.

(w, hs) := io.await(race(handles, io), io);

Resolve to the FIRST handle's result and abort the rest — race with the cleanup done for you (.None if the winner was aborted rather than completed). It drains the list. Panics on an empty list.

This exists because race/any hand back an index and leave the losers running: dropping a JoinHandle DETACHES its task (Tokio's semantics, which is what makes a fire-and-forget io.spawn statement correct), so a caller who wants the losers' work stopped has to abort() each one. The handle's Drop releases its reference to the task; abort-on-drop is deliberately not its semantics.

Every loser is aborted AND joined: the join lets a loser suspended in a cancellable operation be released here rather than when that operation would have completed.

Resolve once some handle COMPLETES (not merely aborts), to its index, or to .None once every handle is terminal without a completion, and hand the list back: (index, handles). Like race, the losers keep running unless aborted (any_first aborts them). Panics on an empty list.

Resolve to the first handle to COMPLETE and abort the rest — any with the cleanup done for you. .None when every handle ended without completing. It drains the list. Panics on an empty list. See race_first for why this exists.

Run fut with a deadline: .Ok(v) if it finishes within limit, .Err(TimeoutError.Elapsed) if the deadline fires first (the operand is aborted), .Err(TimeoutError.Aborted) if the operand was aborted on its own (an effect handler unwound it). Millisecond granularity (the timer contract of std/time/sleep). Tokio's time::timeout(d, fut).

r := io.await(timeout(rx.recv(io), Duration.from_millis(i64(200)), io), io);

The operand is a FUTURE, so it may borrow (plans/VALUES_BY_DEFAULT.md §3.13 A4): timeout(s.next(io), d, io) over a &mut stream works, and the future timeout returns is then a borrowing future too, awaited where it is made. The operand runs as a scoped child task, and is aborted and joined before timeout resolves, so no borrow outlives the call. The operand's effect type is Io, as timeout's own is; an operand with a richer bundle is not accepted yet (issues/2026-10-20-an-effect-binder-bound-only-through-a-future-parameter-resolves-to-io.md).

To have the deadline abort the work, pass the work's future itself: it runs as timeout's scoped child and is aborted when the deadline fires. A task that is already spawned is timed out through its join future, timeout(h.join(io), d, io), which resolves to .Ok(Option(T)). On the deadline that drops the join future and with it the handle, which DETACHES the task: it keeps running (Tokio's semantics for a dropped JoinHandle). Before §3.13 A4, timeout took the JoinHandle and aborted the task on the deadline.

An operand that finishes before the deadline leaves nothing behind: aborting the deadline task deregisters the armed timer in the I/O backend and releases the deadline task there and then. Until that cancel path existed the timer kept counting and held ~256 bytes per call for the whole remaining deadline (issues/fixed/timeout-deadline-timer-future-leak.md).

Run two futures and resolve to the first one to COMPLETE, aborting and joining the other: .Some(.First(a)) or .Some(.Second(b)), or .None when both were aborted (an effect handler unwound each) without a completion. An operand that aborts does not win; the other keeps running. When both have completed by the time the wait resumes, the first wins (a biased select, like Tokio's select! with biased;).

match(
  io.await(select(rx.recv(io), sleep(u64(50)), io), io),
  .Some(.First(msg)) => handle(msg),
  .Some(.Second(_)) => println("idle"),
  .None => ()
);

The operands are FUTURES, so they may borrow (plans/VALUES_BY_DEFAULT.md §3.13 A4), as timeout's does: each runs as a scoped child task with the Io bundle, the loser is aborted and joined before select resolves, and the future select returns borrows what the operands borrow. The two may not lend overlapping places when either side is &mut (decision 38 B): select(s.next(io), s.next(io), io) is E0910.

Take ownership of a spawned operand as a scoped child.

The scoped task's state (Aborted once it was joined).

Abort the scoped task (a terminal one is left alone).

Add the scoped task to the join wait w.

Join the scoped task: its result, or .None if it was aborted. Called once, after which the task is no longer scoped (the join owns it).