skip to content

In C++20, what happens step by step at co_await on an awaiter for an async socket read, and what may await_suspend return?

level: seniorimportance: should knowfreq 40%

answer

  1. await_transform, then operator co_await
  2. ready? suspend? resume?
  3. void, bool or a handle
  4. symmetric transfer
  5. do not touch the awaiter after publishing

basics

~20 s

co_await calls await_ready; if it returns false the coroutine suspends and await_suspend(handle) runs, typically starting the read and storing the handle. When something resumes the handle, await_resume's result becomes the value of the co_await. await_suspend may return void, bool or a coroutine_handle.

solid answer

~40 s

The operand first passes through the promise's `await_transform` if it has one, then through any `operator co_await`, giving the **awaiter**. `await_ready()` is asked first; `true` skips suspension. Otherwise the coroutine is **suspended** and `await_suspend(h)` is called with its `std::coroutine_handle`. For a socket read it registers the read and hands `h` to the completion callback. Its return type decides what happens next: `void` returns to the caller or resumer; `bool` returns there on `true` but resumes the coroutine immediately on `false` (the read finished synchronously); a `std::coroutine_handle<Z>` is resumed instead — **symmetric transfer**, with `std::noop_coroutine()` meaning "return". When the callback calls `h.resume()`, the coroutine continues on that thread and `await_resume()` supplies the value. Once `h` is published, another thread may resume and destroy the frame, so `await_suspend` must not touch the awaiter afterwards.

code

cpp · 37 lines
cpp
#include <coroutine>
#include <cstdio>
#include <exception>
#include <string>
#include <thread>
struct Detached {  // starts eagerly, frees its own frame when it finishes
    struct promise_type {
        Detached get_return_object() { return {}; }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_never final_suspend() noexcept { return {}; }
        void return_void() {}
        void unhandled_exception() { std::terminate(); }
    };
};

struct FakeRead {  // an awaiter standing in for an async socket read
    std::thread* io;
    std::string data;
    bool await_ready() const noexcept { return false; }  // never ready: suspend
    void await_suspend(std::coroutine_handle<> h) {
        std::thread* slot = io;  // copy now: once the thread starts, *this may be gone
        *slot = std::thread([this, h] { data = "GET /index.html"; h.resume(); });
    }
    std::string await_resume() { return std::move(data); }  // the co_await's value
};

Detached serve(std::thread* io) {
    std::string req = co_await FakeRead{io, {}};
    std::printf("got \"%s\" on the I/O thread\n", req.c_str());
}

int main() {
    std::thread io;
    serve(&io);  // returns at the first suspend point
    std::printf("serve() returned while the read is pending\n");
    io.join();
}

go deeper

for a junior

Recall that co_await pauses the coroutine until the awaited thing is ready and then gives back a value.

for a middle

Name await_ready, await_suspend and await_resume, say when each runs, and explain what the void, bool and handle returns of await_suspend do.

for a senior

Write an I/O awaiter that publishes the handle last, explain symmetric transfer, and say which thread the coroutine resumes on.

for a principal

Make thread affinity and cancellation explicit in the codebase's awaiters, since the language leaves both to whoever writes await_suspend.

## The pieces C++20 splits waiting into three roles: - an **awaitable** — what you write after `co_await`, such as a `read(socket, buffer)` call result; - an **awaiter** — the object with `await_ready`, `await_suspend` and `await_resume`; - the coroutine's **handle**, a `std::coroutine_handle<Promise>` that can later `resume()` it. Often the awaitable is its own awaiter. When it is not, the compiler gets the awaiter in two steps: if the promise type has an `await_transform` member, the operand becomes `p.await_transform(operand)`; then, if an `operator co_await` applies, its result is used. ## The sequence at `co_await` 1. Evaluate the awaiter `e`. 2. Call `e.await_ready()`. If it returns `true`, skip to step 5 without suspending — the data is already there. 3. Otherwise the coroutine is **suspended**: its locals and the resume point are saved in the frame. 4. Call `e.await_suspend(h)`. Its return type decides what happens next (table below). 5. When the coroutine resumes, call `e.await_resume()`; its result — type and value category included — is the value of the whole `co_await` expression. If `await_suspend` exits with an exception, the standard says the exception is caught, the coroutine is resumed and the exception is immediately rethrown inside it. | `await_suspend` returns | Effect | |---|---| | `void` | control returns to the coroutine's caller or resumer | | `bool` | `true`: return to the caller or resumer; `false`: resume this coroutine at once | | `std::coroutine_handle<Z>` | that coroutine is resumed; returning `std::noop_coroutine()` means "just return" | The `bool` form suits I/O that sometimes completes synchronously: try the read, return `false` if bytes were already available. The handle form is **symmetric transfer**: when one coroutine finishes and its awaiting parent should continue, `await_suspend` returns the parent's handle, and implementations can make that a tail call, so long chains of coroutines do not grow the native stack. ## An async socket read In the example, `FakeRead` stands in for a socket read: - `await_ready()` returns `false`: a read is never assumed complete. - `await_suspend(h)` starts the "I/O" on a separate thread and gives it `h`. - The I/O thread stores the bytes and calls `h.resume()`. The coroutine continues **on the I/O thread**, not the thread that started it — `co_await` gives no thread affinity unless the awaiter arranges it. - `await_resume()` moves the bytes out, and they become the value of `co_await`. `serve()` returns to `main` at the first suspension, which is why `main` can print while the read is pending. ## The lifetime trap inside `await_suspend` The awaiter is a temporary stored in the coroutine frame. The moment `await_suspend` hands `h` to another thread, that thread may resume the coroutine, finish it and — with `final_suspend` returning `std::suspend_never` — destroy the frame, awaiter included, **while `await_suspend` is still running**. Any access to `this` after the hand-off is then a use-after-free. In the example, `*io = std::thread(...)` would evaluate the right operand first and then read the member `io` from a possibly destroyed awaiter, so the code copies `io` into a local before starting the thread. Rules that follow: - publish the handle **last**; - copy anything you need from the awaiter into locals first; - never assume the coroutine is still suspended after the hand-off. ## Common awaiter shapes - `std::suspend_always`: `await_ready()` returns `false` and `await_suspend` does nothing, so the coroutine simply stops and returns control. - `std::suspend_never`: `await_ready()` returns `true`, so no suspension happens. - **Ready-if-available**: `await_ready()` checks whether the data is already buffered, avoiding a suspension on the fast path. - **Post-to-loop**: `await_suspend` pushes the handle onto an event loop's queue, so the coroutine resumes on that loop's thread. ## Where the coroutine resumes Because whoever calls `resume()` runs the rest of the coroutine, the awaiter decides the thread. A UI or game loop usually wants an awaiter that posts the handle back to its own queue instead of resuming inline; that choice belongs to the framework, not to the language.

  • Why return a coroutine_handle from await_suspend instead of calling h2.resume() inside it?
    Calling `resume()` inside `await_suspend` nests the second coroutine's execution on top of the current native stack frame; a long chain of coroutines completing each other can overflow the stack. Returning the handle lets the compiler resume it after the current coroutine is fully suspended, and implementations turn that into a tail call — symmetric transfer — so the stack depth stays constant.
  • What does a promise's await_transform let a library do?
    Every `co_await` operand in that coroutine (except the implicit ones from `co_yield`, `initial_suspend` and `final_suspend`) is first passed through `p.await_transform(operand)`. A task type can use it to attach its scheduler or cancellation token to each awaited operation, to restrict which types may be awaited, or — as `std::generator` does by deleting it — to forbid `co_await` entirely.

  • co_await always suspends the coroutine.
  • After co_await the coroutine continues on the thread that started it.
  • await_suspend returning false keeps the coroutine suspended.
  • It is safe to use the awaiter's members after handing the handle to another thread.
  • co_await creates a new thread to run the awaited work.

Assumes C++23; the awaiter protocol and std::coroutine_handle are C++20 and unchanged since.