Async I/O
The network and DNS resources expose an *Async verb that returns a Future<T>. From the caller’s side the API is the same whatever backs it:
you await the handle, handle errors with try / catch, and compose it
with other Future<T> handles.
What this page covers: the socket, DNS and HTTP async verbs · what backs each one · timeouts and error handling across an
await· what the reactor cannot do (regular files, and theasync fnrestrictions) · the runtime mechanism under both.
Two backings, neither blocks a thread
Async I/O is served by two mechanisms. Both let the calling coroutine suspend while the work is pending, and neither parks an OS thread on a single operation.
*Async verb on a socket *Async verb on a DNS name / HTTP
─────────────────────── ───────────────────────────────
fd set non-blocking no fd exists the reactor can watch
│ │
▼ ▼
registered with the OS queue job queued to the offload pool
(epoll / kqueue / IOCP) (a worker runs the blocking call)
│ │
▼ ▼
event loop wakes the coroutine event loop wakes the coroutine
when the fd is reported ready when the job publishes its result - Reactor I/O (sockets). The socket is put in non-blocking mode and its fd is registered with the OS event queue: epoll on Linux, kqueue on macOS and the BSDs, IOCP on Windows. The event loop wakes the coroutine the moment that fd is reported ready.
- Offload workers (DNS, and a hostname
connectAsync). No fd exists that the reactor could watch, so the blocking call is queued to a pool of OS worker threads. The event loop wakes the coroutine when the job publishes its result.
The difference matters for scale. Reactor I/O handles thousands of simultaneous connections with no extra threads and no parked thread. Offload work runs on a pool that keeps a few workers and grows past them on demand, so a burst of DNS lookups drains in waves, each wave a worker, rather than one lookup at a time.
HTTP is a third case. HttpClient::getAsync and postAsync are written in
Axle and run the blocking round-trip as a task started with spawn. They
answer the same Future<string> (see HTTP below).
File I/O has no async verb. A regular file has no readiness to report, so
there is no fd the reactor could watch. File work belongs in the task
world: hand it to a spawned task and await the result. See Tasks and async, Files go to the task world.
Sockets
use std::net::Socket;
use std::net::ServerSocket;
// The accept loop lives in a PLAIN `fn`: an `await` inside a loop is
// only restricted in an `async fn` (E0721). Here each `await
// acceptAsync()` drives the event loop, which in turn advances every
// in-flight client coroutine, so the loop is the event-loop driver.
fn serve(port : i32) : void ! IOException {
let srv : ServerSocket = new ServerSocket(port);
srv.bind();
while (true) {
let peer : Socket = await srv.acceptAsync(); // drives the loop
handleClient(peer); // fire-and-forget coroutine
}
}
fn buildResponse(req : string) : string {
return "HTTP/1.1 200 OK\r\nContent-Length: " + req.length + "\r\n\r\n" + req;
}
async fn handleClient(peer : Socket) : void ! IOException, IllegalArgumentException {
let req : string = await peer.readAsync(4096);
let resp : string = buildResponse(req);
await peer.writeAsync(resp);
peer.close();
}
fn main() : i32 ! IOException {
serve(8080);
return 0;
} acceptAsync, readAsync and writeAsync integrate directly with the
event loop’s reactor. Each await srv.acceptAsync() drives the loop, which
watches the server socket’s fd and every client socket’s fd at once. The
moment any of them is ready, the matching coroutine advances. No thread is
blocked. Every client is its own coroutine, costing only its heap frame.
Socket methods
| Method | Returns | Throws | Notes |
|---|---|---|---|
connectAsync() | Future<void> | IOException | TCP handshake; suspends until connected. An IP literal registers one I/O wait. A hostname resolves and connects on an offload worker |
readAsync(max) | Future<string> | IOException, IllegalArgumentException | Reads up to max bytes. Received bytes holding a NUL are refused with IllegalArgumentException rather than copied; use readBytes for binary data |
writeAsync(data) | Future<void> | IOException | Writes all bytes; suspends until drained |
ServerSocket.acceptAsync() | Future<Socket> | IOException | Accepts the next incoming connection |
Each of these throws IOException, raised at the await; readAsync also
throws IllegalArgumentException when the bytes it received hold a NUL, which
an Axle string cannot carry. The blocking counterparts (connect, readInto, writeFrom, accept) are documented with the rest of the
surface in the stdlib overview.
Socket.close() is synchronous and can itself raise IOException. Its
signature is void ! IOException.
Echo server: many clients, one thread
Inside an async fn, an await may not sit in a loop (E0721). A
multi-message session therefore recurses: it handles one message, then fires
the next round as a fresh coroutine that the loop drives. close() can raise IOException, so the coroutine declares it in its ! set. The
fire-and-forget caller never consumes the handle, so nothing has to catch
the error.
The same restriction has a second half. An async fn body cannot call a
function whose frame parks (E0767). A parking frame is one that reaches
an await, a wait on a channel, a lock, a latch, a semaphore, a Thread join, a blocking socket call, a blocking name lookup, the prelude sleep(ms) or Process.waitFor. Such a callee would park the stack it runs on, and
inside a state machine that stack belongs to the machine, with no suspension
point between them.
Entering synchronized is the same wait and draws the same refusal. The ...Async verbs (acceptAsync, readAsync, dnsResolveAsync, and so on)
are the forms a machine awaits instead.
Distance makes no difference. The reach is followed through the frame edges,
so however many plain calls sit between the machine and the wait, the
refusal holds. A constructor is reached the same way: new T(args) runs the
constructor body on the async frame, so building an object whose
constructor reaches an await is refused with the same E0767.
A call target the compiler cannot name is also refused. That covers a call
through a function value, and a body that lives in another compilation unit.
Nothing establishes that such a callee does not park, and a machine may not
share its stack with a body it cannot vouch for. To reach such a function
(or such a construction), go through spawn, whose task owns its own frame,
or keep it out of the async body. A plain caller, such as the echoServer loop below, is unaffected. That is why a server’s accept loop lives in a
plain fn.
use std::net::Socket;
use std::net::ServerSocket;
async fn echoClient(peer : Socket) : void ! IOException {
try {
let msg : string = await peer.readAsync(1024);
if (msg.length == 0) {
peer.close(); // peer hung up
return;
}
await peer.writeAsync(msg);
echoClient(peer); // next round, as its own machine
} catch e : IOException | IllegalArgumentException {
peer.close(); // connection error: clean up
}
}
// Plain `fn` accept loop: await-in-loop is legal outside an `async fn`.
fn echoServer(port : i32) : void ! IOException {
let srv : ServerSocket = new ServerSocket(port);
srv.bind();
while (true) {
let peer : Socket = await srv.acceptAsync();
echoClient(peer); // registers a coroutine; does NOT await it here.
// The loop drives it automatically.
}
}
fn main() : i32 ! IOException {
echoServer(9000);
return 0;
} echoClient(peer) creates a new Future<void> without awaiting it. The
event loop picks it up on the next round. Thousands of clients can be
connected at once, and each is its own suspended coroutine, costing only its
heap frame.
Note: in the recursive shape, every open recursion level keeps its coroutine frame alive until its callee resolves. A session that never reaches its base case therefore holds one frame per connection for the life of the process. The recursion above ends when the peer hangs up or errors. A shape with no such exit grows without bound.
Files: use a task, not the reactor
There is no File async verb. A regular file is not a socket. It has no
readiness to report, so there is no fd the reactor could watch and no
coroutine to await. File work therefore runs in the task world: spawn a Future per file and await the results.
Three file reads. The read blocks in the kernel, and it is made on the
carrier. The task that made it holds that carrier thread until the read
returns. Two such tasks that share a carrier read one after the other. Tasks
the pool spreads over several carriers read side by side. spawn gives each
read a frame of its own while it waits, but overlap is a property of the
pool’s placement, not a promise. Overlap for sockets comes from the reactor,
which has an fd to watch.
use std::io::BufferedReader;
use std::io::FileInputStream;
fn loadLines(path : string) : i32 ! IOException, FileNotFoundException {
let reader : BufferedReader = new BufferedReader(new FileInputStream(path));
defer reader.close();
let mut n : i32 = 0;
while (reader.hasMoreLines()) {
reader.readLine();
n = n + 1;
}
return n;
}
// `spawn`ing a throwing function carries its error set to the caller,
// so `main` re-declares `! IOException, FileNotFoundException`.
fn main() : i32 ! IOException, FileNotFoundException {
let paths : string[3] = ["a.txt", "b.txt", "c.txt"];
let mut jobs : Future<i32>[3];
for (i of 0..3) { jobs[i] = spawn loadLines(paths[i]); } // three tasks filed
let mut total : i32 = 0;
for (j of 0..3) { total = total + await jobs[j]; }
return total;
} The point of this shape is where the work happens, not how fast it runs.
Each loadLines runs in a frame that the caller’s locals do not have to
survive, and the awaits report one number per file.
Note:
reader.readLine()answers""at end of file, but it also answers""for a blank line. Loop onhasMoreLines(), as above, and not on the length of the line. A check such aswhile (!line.isEmpty())would stop at the first blank line.
See Files and I/O for the synchronous file surface, and The task world.
DNS
A name lookup blocks for as long as the resolver takes, and it has no fd the reactor could watch. It therefore runs on the offload pool:
use std::dns::dnsResolveAsync;
fn main() : i32 ! IOException {
let hosts : string[] = [
"api.example.com",
"cdn.example.com",
"db.example.com",
];
// Array sizes are integer literals in Axle, so size the handle array
// to the host count.
let mut lookups : Future<string>[3];
for (i of 0..3) {
lookups[i] = dnsResolveAsync(hosts[i]); // all lookups queued now
}
// `await` inside a loop is fine here: `main` is a plain `fn`, not an
// `async fn`, which is what E0721 restricts. Each await drives the loop.
for (j of 0..3) {
let ip : string = await lookups[j]; // first IP, or "" on none
println(ip);
}
return 0;
} All three lookups are submitted before the first is awaited. They drain as the pool’s workers free up. The pool keeps four workers for good and starts another when a job arrives while every worker is busy. The lookups therefore overlap up to the pool’s ceiling rather than four at a time. The driving loop is parked, not spinning, the whole time.
| Function | Returns | Throws | Notes |
|---|---|---|---|
dnsResolveAsync(host) | Future<string> | IOException | First IP address, or "" when the lookup has no result. Failures raise at the await. Import with use std::dns::dnsResolveAsync; |
The synchronous dnsResolve(host) and dnsResolveAny(host) sit in the same
module; they are not async.
HTTP
HttpClient::getAsync and postAsync run the full HTTP round-trip (connect,
request, response) as a spawned task. They answer a Future<string> that
you await:
use std::net::HttpClient;
// `! IOException`: starting the work with `getAsync` is itself a throwing
// call (its signature declares it), so the call sites need the error set.
// The per-request error at the `await` is handled by the `try`.
fn main() : i32 ! IOException {
let urls : string[] = [
"https://api.service-a.com/data",
"https://api.service-b.com/data",
"https://api.service-c.com/data",
];
let mut pending : Future<string>[3];
for (i of 0..3) {
pending[i] = HttpClient::getAsync(urls[i]); // all three filed as tasks
}
let mut ok : i32 = 0;
for (j of 0..3) {
try {
let body : string = await pending[j];
if (body.length > 0) { ok = ok + 1; }
} catch e : IOException {
// skip the failed endpoint
}
}
return ok;
} | Method | Returns | Notes |
|---|---|---|
HttpClient::getAsync(url) | Future<string> | GET; the body as a string |
HttpClient::getAsync(url, opts) | Future<string> | GET under a RequestOptions record |
HttpClient::postAsync(url, body) | Future<string> | POST with a body |
HttpClient::postAsync(url, body, opts) | Future<string> | POST under a RequestOptions record |
These are static. Each body is spawn of a blocking helper, so the handle
is stackful-backed. The helper is the same blocking exchange the synchronous
path runs, filed as a task instead of called inline. Only the body is
carried, as text. The response owns its buffer, and handing that buffer
across a thread would need an ownership answer this shortcut does not give.
Three requests. The exchange itself never awaits. Each of its blocking
steps (the connect, the reads, the writes) leaves the carrier and parks the
task while the kernel works. The three round-trips therefore overlap: while
one task waits on the kernel, its carrier runs whatever else it holds. What
the Future<T> adds is the handle. All three are filed before the first is
awaited, so the code reads as “start three, settle three” rather than three
nested calls. Each response is released where it is consumed.
The overlap is not a guarantee of one core per request. The three are handed to the carrier pool and taken by whichever carriers are free. On a machine with spare cores each may parse on a thread of its own. A fourth and fifth exchange, however, share those threads with these. The waits also run one level lower, on the offload pool, which grows past its core workers on demand up to a ceiling. A call past that ceiling queues.
A program whose wall-clock time is dominated by HTTP processing, rather
than round-trips, wants a thread it does not share. Put each exchange on its
own platform thread with Thread::run(f, args...), .join() the handles,
and hand each result back through a channel or a Shared<T>. A Thread returns no value. See The third backing.
TLS. Both http:// and https:// are served. TLS verifies the server
against a trust store compiled into the runtime (webpki-roots), not the
operating system’s store. A program that connects on one machine therefore
connects on all of them. A certificate the store does not vouch for raises IOException with the reason.
Timeouts on any async I/O
.timeout(ms) works on every Future<T> on this page, whichever backing it
holds. What expiry does to the work differs:
| Backing | Verbs | On expiry |
|---|---|---|
| Coroutine | every *Async socket verb and dnsResolveAsync | the coroutine is cancelled |
| Stackful (spawned task) | HttpClient::getAsync / postAsync | the caller stops waiting; the spawned exchange runs on to its own end and its result is dropped |
use std::net::HttpClient;
use std::dns::dnsResolveAsync;
async fn reliableResolve(host : string) : string {
try {
// `.timeout(ms)` IS the await-with-deadline: no extra `await` needed.
return dnsResolveAsync(host).timeout(5000);
} catch e : TimeoutException {
return "";
} catch e : IOException {
return ""; // the lookup itself can fail, too
}
}
// HTTP carries its own deadline, set on the request rather than on the
// wait. A `.timeout(ms)` on `getAsync`'s handle stops the wait but leaves
// the exchange running. The request deadline ends the exchange itself, and
// bounds a peer that accepts and then says nothing.
fn reliableFetch(url : string) : string {
try {
return HttpClient::request(url)
.timeoutMillis(3000)
.get()
.body();
} catch e : IOException {
return "";
}
} When the deadline hits, TimeoutException is thrown and the handle is spent.
A coroutine is cancelled. A spawned task runs on. The same try / catch catches both timeout and I/O errors. For HTTP, the request deadline travels
with the request and surfaces as IOException.
Error handling
Every async I/O error is raised at the await, so you handle it the same way
as a synchronous error:
use std::net::HttpClient;
async fn safeGet(url : string) : string {
try {
return await HttpClient::getAsync(url);
} catch e : IOException {
return "error: " + e.message;
}
} You can also let the error propagate by declaring it in the ! set of the async fn. The caller’s await then re-throws it.
Under the hood
Reactor I/O (sockets)
Non-blocking sockets use the platform’s event notification: epoll on Linux, kqueue on macOS and the BSDs, IOCP on Windows.
- Unix: the fd is set non-blocking and registered with the event queue.
A connect that would block reports
EINPROGRESS, and the fd is then watched for writability. - Windows: the same handle-based registration, against the platform’s
completion queue. From the caller’s side the
Future<T>is identical. Only the platform seam differs.
The fd is registered with the OS event queue once, as a oneshot, keyed by
the handle. A round of the event loop then attempts only the handles the
kernel reported ready. It does not rescan every pending operation. An attempt
that returns WouldBlock re-arms its oneshot. An attempt that completes
releases the key it was waiting on. A handle’s registration goes with its
last key. Several futures may wait on one handle, and a ready handle names
all of them.
The event queue holds the interest set inside the kernel. It sleeps the OS thread until any registered fd becomes ready, then returns just the ready ones. One wait watches a thousand sockets. The thread uses no CPU while nothing is happening, then wakes and resumes exactly the coroutines whose fds fired.
event loop (one OS thread) kernel interest set
────────────────────────── ───────────────────
attempt the fds reported ready ──► none left
wait(timeout) ── sleeps ──► fd4 : socket, no data yet
(thread parked, no CPU burned) fd7 : socket, no data yet
fd9 : socket, bytes arrive!
kernel returns: [handle9] ◄──────────────┘
attempt handle9: complete, disarm fd9
resume coroutine C9 from its saved state
loop again ──► wait(timeout) The wait is bounded by the nearest pending timer deadline and, failing that, by a short ceiling. A timer therefore never oversleeps. A passively-ready dependency (a task await, a queued offload job) is re-checked promptly, even though no fd will ever fire for it.
Compare the task world. A thousand blocked reads there would be a thousand stacks, with pages committed for each. A blocking call has no fd to wait on, so a thousand of them would also fill the offload pool’s workers and queue behind one another. Here it is one thread, one kernel wait, and a thousand cheap coroutine frames. That is why reactor I/O scales to connection counts a stack-per-wait design cannot reach.
Each OS thread that drives coroutines has its own event queue and its own task table, so two loops never contend.
Offload workers
A pool of OS worker threads drains a shared job queue. A worker runs the blocking call and publishes the result (a success value, or an exception class and message) into the job’s slot. The event loop polls that slot.
| Parameter | Value | Meaning |
|---|---|---|
| Core workers | 4 | kept for the life of the process |
| Ceiling | 256 | a worker is added when a job arrives and every worker is busy, up to this bound |
| Idle retirement | 10 s | a worker beyond the core count that stays idle this long leaves |
A worker is reused across jobs; it is not one thread per operation. A call
past the ceiling waits its turn. The calling coroutine suspends the instant
the job is submitted and resumes once the slot is filled. Errors from the
worker are raised on the consuming thread at the await, so try { await op } catch works as usual.
The task world shares this pool. A blocking socket call made from a stackful
task (a synchronous connect, accept, read or write) is queued to the same
pool. It parks the task while it runs, which keeps the carrier free to run
the tasks that share its thread. The two worlds therefore compete for the same
slots, and the ceiling applies to both.
The runtime’s own blocking submits are what reach this pool. They come from
the stdlib’s awaits (a name lookup, a hostname connectAsync), from the
blocking socket verbs above, and from Process.waitFor. An ordinary blocking
call in your own Axle code (a file read or write, a call into C) is not
submitted. It holds the carrier it was made on.
The pool starts on the first offload and is never torn down. A program that never offloads pays for no worker at all.
Limits / Uncabled
| Feature | State | Detail / workaround |
|---|---|---|
| Async verb for a regular file | Not provided | A file has no readiness for the reactor to watch. Use spawn and await (see Files) |
.timeout(ms) on HttpClient::getAsync / postAsync | Stops the wait, not the exchange | The handle is a spawned task, and a task cannot be cancelled from outside. Set HttpRequest.timeoutMillis(ms) on the request to end the exchange itself |
await inside a loop of an async fn | Refused (E0721) | Move the loop into a plain fn, or recurse through a new coroutine (see the echo server) |
await inside defer, a try with a finally, or synchronized in an async fn | Refused (E0722) | Await before entering the scope. A try with only a catch may await |
Calling a parking function from an async fn | Refused (E0767) | The callee would park the machine’s own stack. Reach it through spawn, or keep it out of the async body. This covers locks, channels, latches, Thread.join, blocking socket calls and name lookups, sleep(ms) and Process.waitFor, at any depth |
| Recursive coroutine session without a base case | Unbounded growth | Each open level keeps a live frame until its callee resolves. Make the recursion end on a real exit |
| Blocking socket waits | Hold an offload worker for as long as they wait | The pool holds at most 256 workers. Past that, later blocking calls (a write that would unblock a peer included) queue behind waits that may never end. Give each connection a readAsync, which waits on the reactor and holds no worker |
The async fn placement errors and their workarounds are tabulated in Tasks and async: Restrictions.
See also
- Tasks and async: the two-worlds overview
- Concurrency primitives: locks and channels
- Stdlib overview: the
std::net,std::ioandstd::dnssurface - Files and I/O: the synchronous file recipes