co_return 关键字与返回值 ​

什么是 co_return ​

co_return 是 C++20 协程中用于结束协程并可选地返回一个最终值的关键字。它的作用类似于普通函数中的 return,但有几个关键区别:

  • 协程中不能使用 return,必须用 co_return
  • co_return 之后协程进入最终挂起点(final_suspend),而不是立即销毁
  • co_return 的值通过承诺对象的 return_value() 或 return_void() 方法传递

co_return 的两种形式 ​

形式调用的承诺方法说明
co_return;promise.return_void()不返回值
co_return expr;(expr 为 void)promise.return_void()表达式类型为 void
co_return expr;(expr 非 void)promise.return_value(expr)返回一个具体值

一个 promise_type 要么定义 return_void(),要么定义 return_value(),不能同时定义两者。

co_return 的执行流程 ​

co_return expr;
    |
    v
调用 promise.return_value(expr)  // 或 return_void()
    |
    v
销毁所有局部变量(逆序)
    |
    v
co_await promise.final_suspend()
    |
    +--- suspend_always → 协程挂起(调用者负责销毁)
    +--- suspend_never  → 协程帧自动销毁

如果协程函数体执行到末尾而没有显式写 co_return;,行为等价于 co_return;——前提是 promise_type 中定义了 return_void()。如果没定义 return_void(),这种情况是未定义行为。

基本示例 ​

cpp
#include <coroutine>
#include <iostream>
#include <string>
#include <optional>
#include <exception>

// ============================
// 示例1:不返回值的协程(return_void)
// ============================

struct VoidTask {
    struct promise_type {
        VoidTask get_return_object() {
            return VoidTask{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }

        // 协程不返回值时定义 return_void
        void return_void() {
            std::cout << "  [promise] return_void() 被调用" << std::endl;
        }

        void unhandled_exception() { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit VoidTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~VoidTask() { if (handle_) handle_.destroy(); }
    VoidTask(const VoidTask&) = delete;
    VoidTask& operator=(const VoidTask&) = delete;
    VoidTask(VoidTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
    bool done() const { return !handle_ || handle_.done(); }
};

// 显式 co_return;
VoidTask void_coroutine_explicit() {
    std::cout << "执行一些工作..." << std::endl;
    co_return;  // 显式结束,调用 return_void()
}

// 隐式 co_return(函数体末尾)
VoidTask void_coroutine_implicit() {
    std::cout << "执行一些工作..." << std::endl;
    // 没有 co_return,但因为有 co_await,编译器知道这是协程
    co_await std::suspend_never{};
    std::cout << "工作完成" << std::endl;
    // 隐式 co_return; → 调用 return_void()
}

void void_demo() {
    std::cout << "--- 显式 co_return ---" << std::endl;
    auto t1 = void_coroutine_explicit();
    t1.resume();

    std::cout << "\n--- 隐式 co_return ---" << std::endl;
    auto t2 = void_coroutine_implicit();
    t2.resume();
}

// ============================
// 示例2:返回值的协程(return_value)
// ============================

template<typename T>
struct ValueTask {
    struct promise_type {
        std::optional<T> result;  // 用 optional 存储结果

        ValueTask get_return_object() {
            return ValueTask{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }

        // 协程返回值时定义 return_value
        void return_value(T value) {
            result = std::move(value);
        }

        void unhandled_exception() {
            result = std::nullopt;  // 异常时清空结果
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit ValueTask(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~ValueTask() { if (handle_) handle_.destroy(); }
    ValueTask(const ValueTask&) = delete;
    ValueTask& operator=(const ValueTask&) = delete;
    ValueTask(ValueTask&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    void resume() { if (handle_ && !handle_.done()) handle_.resume(); }
    bool done() const { return !handle_ || handle_.done(); }

    // 获取协程的返回值
    T result() const {
        if (handle_.promise().result.has_value()) {
            return handle_.promise().result.value();
        }
        throw std::runtime_error("协程没有返回值");
    }

    bool has_result() const {
        return handle_.promise().result.has_value();
    }
};

// 返回整数的协程
ValueTask<int> compute_sum(int a, int b) {
    std::cout << "计算 " << a << " + " << b << std::endl;
    co_return a + b;  // 调用 return_value(a + b)
}

// 返回字符串的协程
ValueTask<std::string> greet(const std::string& name) {
    std::string greeting = "你好, " + name + "!";
    co_return greeting;  // 调用 return_value(greeting)
}

// 条件返回
ValueTask<int> conditional_return(int x) {
    if (x > 0) {
        co_return x * 2;     // 正数返回双倍
    } else if (x < 0) {
        co_return -x;         // 负数返回绝对值
    } else {
        co_return 0;          // 零返回零
    }
    // 每个分支都有 co_return,不会到达末尾
}

void value_demo() {
    auto sum_task = compute_sum(3, 4);
    sum_task.resume();
    std::cout << "结果: " << sum_task.result() << std::endl;

    auto greet_task = greet("C++20");
    greet_task.resume();
    std::cout << "问候: " << greet_task.result() << std::endl;

    auto cond_task = conditional_return(-5);
    cond_task.resume();
    std::cout << "条件返回: " << cond_task.result() << std::endl;
}

// ============================
// 示例3:惰性求值的 Future 模式
// ============================

template<typename T>
struct LazyFuture {
    struct promise_type {
        std::optional<T> result;
        std::exception_ptr exception;

        LazyFuture get_return_object() {
            return LazyFuture{
                std::coroutine_handle<promise_type>::from_promise(*this)
            };
        }

        // 立即启动(eager)
        std::suspend_never initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }

        void return_value(T value) {
            result = std::move(value);
        }

        void unhandled_exception() {
            exception = std::current_exception();
        }
    };

    std::coroutine_handle<promise_type> handle_;
    explicit LazyFuture(std::coroutine_handle<promise_type> h) : handle_(h) {}
    ~LazyFuture() { if (handle_) handle_.destroy(); }
    LazyFuture(const LazyFuture&) = delete;
    LazyFuture& operator=(const LazyFuture&) = delete;
    LazyFuture(LazyFuture&& o) noexcept : handle_(o.handle_) { o.handle_ = nullptr; }

    // 获取结果,如果有异常则重新抛出
    T get() const {
        if (handle_.promise().exception) {
            std::rethrow_exception(handle_.promise().exception);
        }
        return handle_.promise().result.value();
    }
};

LazyFuture<int> compute_factorial(int n) {
    int result = 1;
    for (int i = 2; i <= n; ++i) {
        result *= i;
    }
    co_return result;  // 计算完成后返回结果
}

LazyFuture<double> safe_divide(double a, double b) {
    if (b == 0.0) {
        throw std::runtime_error("除以零");
    }
    co_return a / b;
}

void future_demo() {
    auto fact = compute_factorial(6);
    std::cout << "6! = " << fact.get() << std::endl;

    auto div1 = safe_divide(10.0, 3.0);
    std::cout << "10 / 3 = " << div1.get() << std::endl;

    try {
        auto div2 = safe_divide(10.0, 0.0);
        std::cout << div2.get() << std::endl;  // 会抛异常
    } catch (const std::exception& e) {
        std::cout << "异常: " << e.what() << std::endl;
    }
}

// ============================
// 示例4:co_return 与协程中间挂起点的配合
// ============================

ValueTask<int> multi_step_computation() {
    std::cout << "步骤 1: 初始化" << std::endl;
    int value = 10;

    co_await std::suspend_always{};  // 挂起,让调用者有机会做其他事

    std::cout << "步骤 2: 处理" << std::endl;
    value *= 3;

    co_await std::suspend_always{};  // 再次挂起

    std::cout << "步骤 3: 完成" << std::endl;
    value += 5;

    co_return value;  // 最终返回 10 * 3 + 5 = 35
}

void multi_step_demo() {
    auto task = multi_step_computation();
    task.resume();  // 步骤 1
    std::cout << "  (调用者在步骤 1 和 2 之间做其他事)" << std::endl;
    task.resume();  // 步骤 2
    std::cout << "  (调用者在步骤 2 和 3 之间做其他事)" << std::endl;
    task.resume();  // 步骤 3,执行 co_return
    std::cout << "最终结果: " << task.result() << std::endl;
}

int main() {
    std::cout << "=== void 协程 ===" << std::endl;
    void_demo();

    std::cout << "\n=== 返回值协程 ===" << std::endl;
    value_demo();

    std::cout << "\n=== Future 模式 ===" << std::endl;
    future_demo();

    std::cout << "\n=== 多步计算 ===" << std::endl;
    multi_step_demo();

    return 0;
}

co_return vs return ​

方面returnco_return
适用范围普通函数协程函数
之后行为函数立即结束,栈帧销毁调用 promise 方法,进入 final_suspend
值传递直接返回给调用者通过 promise 间接传递
能否在协程中使用不能必须用这个
可以省略非 void 函数不能省略void 协程可以省略(隐式 co_return;)

适用场景 ​

  • 异步任务返回计算结果(Future/Task 模式)
  • 协程结束时传递最终状态
  • 配合 co_await 实现多步异步计算的最终返回
  • 条件性提前结束协程

常见问题 ​

协程中可以使用普通的 return 吗?

不可以。一旦函数体中出现 co_await、co_yield 或 co_return,该函数就是协程,不能再用普通 return。用 return 会导致编译错误。

return_void 和 return_value 可以同时定义吗?

不可以。一个 promise_type 只能定义其中一个。如果协程需要返回值,定义 return_value();如果不返回值,定义 return_void()。

协程函数末尾没有 co_return 会怎样?

如果 promise_type 定义了 return_void(),行为等同于隐式 co_return;。如果 promise_type 只定义了 return_value(),到达函数末尾是未定义行为。

co_return 之后协程帧会立即销毁吗?

不一定。co_return 之后会执行 co_await promise.final_suspend()。如果 final_suspend() 返回 suspend_always,协程帧不会销毁,需要调用者通过 handle.destroy() 手动销毁。如果返回 suspend_never,协程帧自动销毁。

co_return 可以返回右值引用吗?

可以,只要 return_value() 的参数类型能接受。通常 return_value(T value) 按值接收,配合移动语义即可。

注意事项 ​

  • 协程中禁止使用 return,必须用 co_return
  • promise_type 中 return_void() 和 return_value() 只能定义一个
  • 没有 co_return 的协程末尾行为取决于是否定义了 return_void()
  • co_return 之后局部变量按逆序析构,然后进入 final_suspend
  • 如果 final_suspend 返回 suspend_always,调用者需要手动销毁协程
  • 在 co_return 之后不能再恢复协程(协程已完成)
  • 异常传播通过 unhandled_exception() 处理,不通过 co_return

编译器支持情况 ​

编译器最低支持版本
GCC10.0
Clang14.0
MSVC19.28 (VS 2019 16.8)

总结 ​

co_return 是结束协程并传递最终结果的关键字。它有两种形式:co_return; 调用 promise.return_void(),co_return expr; 调用 promise.return_value(expr)。一个 promise_type 只能定义其中一个方法。执行 co_return 后,协程会销毁局部变量,然后进入 final_suspend() 决定是否销毁协程帧。在实际应用中,co_return 通常用于 Task/Future 模式——协程执行异步计算,最终通过 co_return 把结果存入承诺对象,调用者再通过返回对象的接口获取结果。