Why AsyncStdoutStream Hangs After the First Write in WASI

If your WASI program writes to stdout once and then appears to freeze forever, the problem is usually not the write itself. The hang is typically caused by a mismatch between the polling model, the stream readiness contract, and how AsyncStdoutStream is driven after the first flushable event.

The reproduction linked in the issue demonstrates a classic WASI I/O readiness bug: the first write succeeds because the stream is initially writable, but subsequent writes stall because the code keeps waiting on readiness in a way that is never re-armed correctly.

Understanding the Root Cause

In WASI async I/O, output streams are not simple always-ready sinks. They usually follow a protocol like this:

1. Check how much the stream can accept now.
2. Write only up to that permitted amount.
3. Flush if required by the implementation.
4. Wait for the next readiness signal before writing again.

The bug appears when AsyncStdoutStream is treated like a continuously writable stream without correctly handling the state transition after the first write. In many implementations, the first call works because the stream begins in a writable state. After that, one of these issues causes the hang:

• The code does not flush or drive completion after writing.
• The program waits on a pollable that is no longer valid for the current stream state.
• The runtime expects a write-then-flush-then-await-ready cycle, but the code only performs the first write.
• A readiness future or poll handle is created once and reused incorrectly instead of obtaining a fresh readiness signal for each cycle.

Technically, this is a contract issue between the output stream abstraction and the executor or event loop. If the stream implementation exposes methods equivalent to check_write, write, flush, and subscribe, then the caller must respect that lifecycle. Once the initial capacity is consumed, the runtime will not necessarily progress further unless the pending flush is observed and a new readiness event is awaited.

That is why the first write succeeds and the second appears to block forever: the code is waiting, but not on the right state transition.

Step-by-Step Solution

The fix is to treat AsyncStdoutStream as a backpressure-aware async output stream. Do not assume repeated writes will succeed without checking capacity and flushing.

1. Follow the correct output stream loop

Your write path should:

1. Ask the stream how many bytes are currently writable.
2. If zero, subscribe and await readiness.
3. Write only the allowed number of bytes.
4. Flush the stream.
5. Await write completion/readiness again before continuing if more bytes remain.

async fn write_all_stdout(mut stream: AsyncStdoutStream, mut buf: &[u8]) -> Result<(), Error> {
    while !buf.is_empty() {
        let permit = stream.check_write()?;

        if permit == 0 {
            let pollable = stream.subscribe();
            pollable.ready().await;
            continue;
        }

        let n = permit.min(buf.len());
        stream.write(&buf[..n])?;
        stream.flush()?;

        let pollable = stream.subscribe();
        pollable.ready().await;

        buf = &buf[n..];
    }

    Ok(())
}

The key detail is that the code gets a fresh readiness handle and waits at the correct times. Reusing an old pollable or skipping flush often reproduces the hang.

2. Do not write more than the stream currently permits

If your implementation exposes a write budget, respect it. This is not optional bookkeeping; it is the stream’s backpressure mechanism.

let permit = stream.check_write()?;
if permit > 0 {
    let to_write = permit.min(data.len());
    stream.write(&data[..to_write])?;
}

If you try to force a larger write than the stream can currently accept, some runtimes will return an error while others may stall indirectly due to unmet completion semantics.

3. Flush explicitly

Some WASI stdout implementations buffer internally. If you only write and never flush, the runtime may never transition the stream back into the state your async loop expects.

stream.write(chunk)?;
stream.flush()?;

Even if stdout feels like an unbuffered terminal, the WASI layer may still model completion asynchronously.

4. Re-subscribe after each state transition

A common mistake is subscribing once before the loop and awaiting that same object forever. Instead, obtain a new readiness subscription when you actually need to wait for the next event.

loop {
    let permit = stream.check_write()?;
    if permit == 0 {
        let pollable = stream.subscribe();
        pollable.ready().await;
        continue;
    }

    break;
}

This ensures your code tracks the current stream state, not a stale one.

5. If wrapping stdout, preserve the readiness contract

If your code introduces a wrapper around AsyncStdoutStream, make sure it does not hide required calls to flush or subscribe. A safe wrapper usually centralizes the full write loop:

pub async fn print_line(stream: AsyncStdoutStream, line: &str) -> Result<(), Error> {
    let mut bytes = line.as_bytes().to_vec();
    bytes.push(b'\n');
    write_all_stdout(stream, &bytes).await
}

6. Validate the fix against the reproduction

Use the issue’s linked reproduction and replace any one-shot write logic with a proper async drain loop. If the program previously printed one line and froze, the corrected implementation should continue writing repeatedly without blocking after the first iteration.

Common Edge Cases

• Buffered output never drains: If the host runtime does not progress flushes unless polled correctly, writes can appear stuck even though no error is returned.
• Stale pollable objects: Holding onto an old readiness subscription can leave your task waiting on an event that has already fired or is no longer relevant.
• Partial writes: A successful write does not always mean the whole buffer was accepted. Always advance the slice manually.
• Mixing sync and async stdout access: If some code paths write via synchronous APIs and others use AsyncStdoutStream, ordering and readiness assumptions may break.
• Runtime-specific behavior: Different WASI hosts may vary in how strictly they enforce flush and readiness semantics. Code that accidentally works in one environment may hang in another.
• Executor starvation: If your async runtime is blocked by CPU-heavy work, the stdout task may never get another chance to observe readiness transitions.

FAQ

Why does the first write succeed but the second one hangs?

Because the stream is often initially writable. After that first write, the code must honor backpressure, usually by flushing and awaiting a new readiness signal. If it does not, the stream never re-enters the expected writable state from the caller’s perspective.

Can I fix this by adding retries or sleeps?

No. Busy retries or arbitrary sleeps mask the bug and can make behavior less deterministic. The correct fix is to follow the stream’s async readiness protocol: check capacity, write partially if needed, flush, and await a fresh readiness event.

Is this specific to stdout?

No. The same pattern can affect any WASI output stream. Stdout is just where it becomes obvious first because it is frequently used for logging and test output.

In short, the solution is to stop treating AsyncStdoutStream like a fire-and-forget writer. Treat it as a stateful asynchronous stream with backpressure, and the post-first-write hang goes away.