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(),这种情况是未定义行为。
基本示例
#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
| 方面 | return | co_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
编译器支持情况
| 编译器 | 最低支持版本 |
|---|---|
| GCC | 10.0 |
| Clang | 14.0 |
| MSVC | 19.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 把结果存入承诺对象,调用者再通过返回对象的接口获取结果。