Ch23.2: fast_io's Async Model

1. Four Objects, One Loop

fast_io's async layer is small. Almost every program in this chapter is built from four objects:

The scheduler is created with the io_async tag. The tag selects the platform's best backend; the type alias io_async_scheduler resolves to the concrete owning type, and io_async_observer resolves to its observer.

fast_io::io_async_scheduler sched{fast_io::io_async};
fast_io::io_async_observer observer{sched};

You rarely write the second line. Passing sched to an async function decays it to the observer automatically, exactly as an owning file decays to its observer.

2. The Smallest Complete Program

This is examples/0045.async_io/a+b.cc from the fast_io repository. It reads two integers from a file, adds them, and writes the result to another file, all without blocking the event loop.

#include <fast_io.h>
#include <fast_io_device.h>

namespace fi = ::fast_io;

static fi::io_async_task<> work(fi::io_async_observer sched) throws
{
    fast_io::ibuf_file inb{
        "input.txt", fast_io::open_mode::in | fast_io::open_mode::no_block};
    fast_io::obuf_file outb{
        "output.txt", fast_io::open_mode::out | fast_io::open_mode::no_block};

    std::size_t a{}, b{};
    co_await fi::async_scan(sched, {}, inb, a, b);
    co_await fi::async_println(sched, {}, outb, a + b);
    co_await fi::operations::async_output_stream_flush(sched, {}, outb);
}

int main()
try
{
    fi::io_async_scheduler scheduler{fi::io_async};

    auto task{work(scheduler)};
    task.resume();
    while (!task.done())
    {
        fi::io_async_wait(scheduler);
    }
    task.rethrow_if_error();
}
catch throws(::std::error e)
{
    fi::perrln(e);
    return 1;
}

Read the control flow, not the syntax. work(scheduler) creates a frame and returns a lazy task. It has not run yet. task.resume() enters the body. The first co_await submits a read and suspends. Control returns to main, which calls io_async_wait. When the read completes, the pump resumes the frame, the scan finishes, the print submits a write and suspends again, and the loop continues until the task is done.

The main loop is the entire scheduler. It is single-threaded. The kernel does the waiting; the program only reaps completions and resumes coroutines.

3. The Operations You Should Use

fast_io provides the same I/O vocabulary in synchronous and asynchronous form. Use the high-level operation that matches the protocol. Do not start with raw pread/pwrite unless you are implementing a codec or a parser that genuinely needs a byte window.

The rule is simple: scan for input, print for output, transmit for byte movement. These three operations already handle buffering, partial transfers and the suspend/resume protocol. Dropping to pread/pwrite throws that away and makes you reimplement the hard parts.

4. Backends: One API, Three Engines

The source code does not change between these backends. That is the point of the operation layer. What changes is the requirement on the handle: on Windows, a socket or file used with the async layer must be opened with open_mode::no_block so it is overlapped. On Linux, io_uring does not need the flag, but passing it is harmless and keeps the code portable. On a thread-pool backend, the flag is also harmless.

The no_block name is historical. It does not mean "use non-blocking syscalls everywhere"; it means "make this handle usable by the asynchronous engine". Read it as async-capable.

5. Errors: Exceptions and Herbceptions

Every async operation reports failure through the same error channel as its synchronous counterpart. There are two promise hooks:

• unhandled_exception() receives an ordinary C++ exception that escaped the coroutine body. It must not return normally.
• unhandled_herbception(std::cxx_std_error) receives a fast_io herbception. It stores the error handle in the promise instead of unwinding through the runtime. The parameter is the raw two-word form, {domain, code}, introduced in Ch19.1; the public ::std::error handle used in catch throws (::std::error e) is introduced in Ch3.16. They describe the same error at different layers.

When a coroutine is awaited, await_resume() rethrows the stored error at the co_await site. When a coroutine is driven from main, rethrow_if_error() does the same after done() becomes true. A detached coroutine has nobody to report to: the promise's destructor releases an unreceived error payload, and the failure is silent unless the coroutine handled it itself. That is the correct behavior for a per-connection session that has already disconnected, and the wrong behavior for a supervisor that needs to restart a listener.

The throws marker after the parameter list is this book's herbception syntax. On a compiler without herbceptions, use the ordinary exception syntax; the coroutine structure and the async calls are unchanged. Ch3.16 explains the model in detail.

6. Task Ownership and Detachment

io_async_task owns its frame. The destructor destroys the frame if the task object still holds it. This gives you two safe patterns and one unsafe one:

A coroutine parameter is copied or moved into the frame. Passing a socket by value to a session coroutine therefore transfers ownership to the frame: when the session finishes, the socket closes. Passing a reference would be a bug, because the referenced object may die before the coroutine resumes.

7. Timeouts, Blocking and Flow Control

Every operation takes a posix_statx_timestamp_opt as its second argument. {} means no timeout; a value means the operation fails with a timeout error when the deadline elapses. The timeout is per operation, not per connection. If you want an idle timeout, arm it on each read; if you want a total deadline, compute the remaining time before each operation.

The event loop is cooperative. A CPU-bound loop, a synchronous file read, a mutex wait or a sleep inside a coroutine stops every other coroutine on the same scheduler. Move CPU work to a worker, or break it into chunks that co_await a yield. The async layer schedules I/O; it does not preempt your code.

Flow control is explicit. async_print formats into a buffer and submits the write; if the peer is slow, the write completes slowly or partially. The operation layer handles the partial write, but it does not invent an unbounded queue for you. If you read a stream and write to a slower stream, use async_transmit_* so the read side is throttled by the write side, or add your own bounded queue. An unbounded queue turns a slow client into a memory leak.

Key Takeaways

• One scheduler, one observer, one task type, one event pump. That is the whole model.
• async_scan, async_print and async_transmit are the default tools. Use pread/pwrite only when you are building the layer beneath them.
• open_mode::no_block means async-capable, not "never blocks".
• unhandled_herbception stores the error; co_await or rethrow_if_error() delivers it. Detached tasks are silent.
• Keep an owned task alive until it is done, or detach it. Never drop a suspended task with an operation in flight.
• The loop is single-threaded and cooperative. Blocking work belongs somewhere else.

The next page writes the server: a listener, an accept loop, one detached session per connection, and a supervisor that survives a dead listener.