Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

co_await — awaiting in a coroutine

The co_await expression uses the awaiter protocol to optionally suspend a coroutine and then obtain a result. It does not itself start a thread or provide scheduling; resumption must be arranged by the implementation being used.

Version: C++23; repository compiler flag, production runtime not attested

Syntax

co_await cast-expression

co_await expression marks a possible coroutine suspension point, not a blocking thread wait. Placing such an expression in a function body makes it a coroutine. Its promise type is obtained from std::coroutine_traits, which must provide an appropriate promise_type for the coroutine's return and parameter types (including the object parameter for a non-static member function). The return type itself need not have a nested promise_type. The operator itself creates neither a thread nor a scheduler.

For explicit co_await, if lookup in the promise type finds a declaration of await_transform, the awaitable is the result of calling await_transform on the promise object with the operand as its argument. Otherwise, the awaitable is the original operand. If overload resolution selects an operator co_await for the awaitable, the result of that call is used as the awaiter. Only if the candidate set for operator co_await is empty is the awaitable itself used as the awaiter — after transformation, if one was applied. If the candidate set is nonempty but contains no viable function, the co_await expression is ill-formed. The awaiter provides await_ready(), await_suspend(h), and await_resume(). The expression has the type and value category of the result of await_resume().

The result of await_ready() is contextually converted to bool. If the conversion yields true, the coroutine does not suspend; this includes a class-type result whose explicit operator bool() returns true. If the conversion yields false, the coroutine is suspended and await_suspend(h) is called. If await_suspend returns void, the return itself does not cause the co_await machinery to resume the coroutine. However, await_suspend can resume the coroutine itself or arrange for another thread to resume it, even before the call returns. A bool result of false resumes the coroutine immediately, and returning a coroutine handle transfers execution to the indicated coroutine. await_resume() supplies the result when execution continues.

The example uses std::suspend_always: run() prints start, returns control, and resume() allows it to print resumed. final_suspend() leaves the frame suspended for the Task destructor to release. Never resume a coroutine at its final suspension point; objects used after resumption must still be alive.

This entry targets C++23; the supplied site publishes an evolving draft, not a frozen C++23 text. Production runtime compatibility is not attested.

Examples

#include <coroutine>
#include <exception>
#include <iostream>

struct Task {
    struct promise_type;
    using Handle = std::coroutine_handle<promise_type>;

    struct promise_type {
        Task get_return_object() {
            return Task{Handle::from_promise(*this)};
        }
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() noexcept { std::terminate(); }
    };

    Handle handle;
    explicit Task(Handle h) noexcept : handle(h) {}
    Task(const Task&) = delete;
    Task& operator=(const Task&) = delete;
    ~Task() { handle.destroy(); }
};

Task run() {
    std::cout << "start\n";
    co_await std::suspend_always{};
    std::cout << "resumed\n";
}

int main() {
    auto task = run();
    std::cout << "caller\n";
    task.handle.resume();
}

Result

start
caller
resumed

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources