Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

std::suspend_always — unconditional coroutine suspension

std::suspend_always from <coroutine> is a simple awaitable that suspends a coroutine without producing a value. It does not schedule resumption: managing code must retain a handle and resume or destroy the suspended coroutine.

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

Syntax

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

std::suspend_always from <coroutine> implements the awaiter protocol. await_ready() returns false, await_suspend(std::coroutine_handle<>) does nothing and returns void, and await_resume() does nothing and returns void. All three methods are constexpr, const, and noexcept. In contrast, std::suspend_never returns true from await_ready().

When this object is the actual awaiter, co_await std::suspend_always{}; suspends the coroutine and returns control to its caller or resumer. After resumption, execution continues without obtaining a value. The type does not block the thread, start a timer, or schedule resumption. The promise's await_transform or an overloaded operator co_await can change the selected awaiter.

In the example, initial_suspend() delays execution of the body until the first resume(). The first resumption prints A and reaches the explicit suspension; the second prints B and reaches final_suspend(). The owner's destructor destroys the retained frame. Copying the owner is forbidden to prevent double destruction.

Do not resume a coroutine at its final suspend point or use a handle after its frame has been destroyed. The example's resume() checks done() before resuming. This entry targets compilation with -std=c++23; the supplied document is an evolving draft, not a frozen C++23 publication. Compiler and production-runtime support require local verification.

Examples

#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";
}

Result

created
A
paused
B
finished

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