Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C++

co_await — čekání v coroutine

Výraz co_await používá protokol awaiteru k případnému pozastavení coroutine a následnému získání výsledku. Sám nespouští vlákno ani nezajišťuje plánování; o obnovení musí rozhodnout použitá implementace.

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

Syntaxe

co_await cast-expression

co_await expression označuje možné místo pozastavení coroutine, nikoli blokující čekání vlákna. Vložením takového výrazu do těla funkce se z ní stane coroutine. Typ objektu promise se určuje pomocí std::coroutine_traits, které musí poskytovat odpovídající promise_type pro návratový typ a typy parametrů coroutine (včetně parametru objektu u nestatické členské funkce). Samotný návratový typ nemusí obsahovat vnořený promise_type. Samotný operátor nevytváří vlákno ani plánovač.

Pokud se u explicitního co_await při vyhledání jména await_transform v typu objektu promise najde deklarace, awaitable je výsledek volání await_transform na tomto objektu s operandem jako argumentem. Jinak je awaitable původní operand. Pokud se při výběru přetížení pro awaitable vybere operator co_await, použije se výsledek tohoto volání jako awaiter. Pouze pokud je množina kandidátů pro operator co_await prázdná, použije se jako awaiter samotný awaitable, po případné transformaci. Pokud množina není prázdná, ale neobsahuje žádnou použitelnou funkci, je výraz co_await neplatný. Awaiter poskytuje await_ready(), await_suspend(h) a await_resume(). Výraz má typ a kategorii hodnoty výsledku volání await_resume().

Výsledek await_ready() se kontextově převádí na bool. Pokud převod dává hodnotu true, k pozastavení nedojde. To platí i tehdy, když je výsledkem objekt třídního typu, jehož explicit operator bool() vrací true. Pokud převod dává hodnotu false, coroutine se pozastaví a zavolá se await_suspend(h). Má-li await_suspend návratový typ void, samotný návrat z volání nezpůsobí, že mechanismus co_await coroutine obnoví. Funkce await_suspend ji ale může obnovit sama nebo zařídit, aby ji obnovilo jiné vlákno, a to i před návratem z volání. Výsledek typu bool s hodnotou false coroutine okamžitě obnoví a vrácení handle coroutine předá provádění uvedené coroutine. await_resume() poskytne výsledek při pokračování provádění.

Příklad používá std::suspend_always: run() vypíše start a předá řízení; resume() jí umožní vypsat resumed. final_suspend() ponechá frame pozastavený, aby jej mohl uvolnit destruktor Task. Coroutine nikdy neobnovujte v jejím konečném bodě pozastavení; objekty používané po obnovení musí stále existovat.

Tento záznam se vztahuje k C++23; uvedený web publikuje průběžně se vyvíjející návrh, nikoli neměnný text C++23. Kompatibilita s produkčním běhovým prostředím není potvrzena.

Příklady

#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();
}

Výsledek

start
caller
resumed

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje