Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::suspend_always — suspensão incondicional de uma coroutine

std::suspend_always de <coroutine> é um awaitable simples que suspende uma coroutine sem produzir um valor. Não agenda a sua retoma: o código que a gere tem de conservar um handle e retomar ou destruir a coroutine suspensa.

Versão: C++23; repository compiler flag, production runtime not attested

Sintaxe

#include <coroutine>
co_await std::suspend_always{};

std::suspend_always de <coroutine> implementa o protocolo awaiter. await_ready() devolve false, await_suspend(std::coroutine_handle<>) não faz nada e devolve void, e await_resume() também não faz nada e devolve void. Os três métodos são constexpr, const e noexcept. Em contrapartida, std::suspend_never devolve true em await_ready().

Quando este objeto é o awaiter efetivo, co_await std::suspend_always{}; suspende a coroutine e devolve o controlo ao chamador ou a quem a retoma. Após a retoma, a execução continua sem obter um valor. O tipo não bloqueia a thread, não inicia um temporizador nem agenda a retoma. await_transform da promise ou um operator co_await sobrecarregado podem alterar o awaiter selecionado.

No exemplo, initial_suspend() adia a execução do corpo até à primeira chamada a resume(). A primeira retoma escreve A e chega à suspensão explícita; a segunda escreve B e chega a final_suspend(). O destrutor do proprietário destrói o frame guardado. A cópia do proprietário é proibida para evitar uma destruição dupla.

Não retome uma coroutine no seu ponto de suspensão final nem use um handle depois de o respetivo frame ter sido destruído. O resume() do exemplo verifica done() antes de retomar. Esta entrada destina-se à compilação com -std=c++23; o documento fornecido é um rascunho em evolução, não uma publicação definitiva de C++23. O suporte do compilador e do ambiente de execução de produção tem de ser verificado localmente.

Exemplos

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

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

    std::coroutine_handle<promise_type> handle;

    explicit Task(std::coroutine_handle<promise_type> h) : handle(h) {}
    Task(const Task&) = delete;
    Task& operator=(const Task&) = delete;
    ~Task() { handle.destroy(); }

    void resume() {
        if (!handle.done()) handle.resume();
    }
};

Task work() {
    std::cout << "A\n";
    co_await std::suspend_always{};
    std::cout << "B\n";
}

int main() {
    auto task = work();
    std::cout << "created\n";
    task.resume();
    std::cout << "paused\n";
    task.resume();
    std::cout << "finished\n";
}

Resultado

created
A
paused
B
finished

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes