Axle v0.22.0

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 the async fn restrictions) · 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

MethodReturnsThrowsNotes
connectAsync()Future<void>IOExceptionTCP 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, IllegalArgumentExceptionReads 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>IOExceptionWrites all bytes; suspends until drained
ServerSocket.acceptAsync()Future<Socket>IOExceptionAccepts 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 on hasMoreLines(), as above, and not on the length of the line. A check such as while (!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.

FunctionReturnsThrowsNotes
dnsResolveAsync(host)Future<string>IOExceptionFirst 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;
}
MethodReturnsNotes
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:

BackingVerbsOn expiry
Coroutineevery *Async socket verb and dnsResolveAsyncthe coroutine is cancelled
Stackful (spawned task)HttpClient::getAsync / postAsyncthe 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.

ParameterValueMeaning
Core workers4kept for the life of the process
Ceiling256a worker is added when a job arrives and every worker is busy, up to this bound
Idle retirement10 sa 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

FeatureStateDetail / workaround
Async verb for a regular fileNot providedA file has no readiness for the reactor to watch. Use spawn and await (see Files)
.timeout(ms) on HttpClient::getAsync / postAsyncStops the wait, not the exchangeThe 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 fnRefused (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 fnRefused (E0722)Await before entering the scope. A try with only a catch may await
Calling a parking function from an async fnRefused (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 caseUnbounded growthEach open level keeps a live frame until its callee resolves. Make the recursion end on a real exit
Blocking socket waitsHold an offload worker for as long as they waitThe 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

asyncfuturesionetworkingsockets