co_return Statement

The co_return statement is a C++20 control flow keyword used exclusively within a coroutine to terminate its execution and optionally produce a final result. Its presence in a function body is one of the syntactic triggers that instructs the compiler to transform the function into a state machine rather than a standard subroutine.

Syntax

co_return expression;
co_return { braced-init-list };
co_return; 

Underlying Mechanics

Unlike a standard return statement, which places a value in a register or on the stack and pops the stack frame, co_return interacts directly with the coroutine’s associated promise_type. The compiler translates the co_return statement into a specific sequence of method calls on the promise object based solely on the type of the operand.

1. Non-Void Return

When co_return expression; or co_return { braced-init-list }; is evaluated, and the operand is not of type void, the compiler translates it to:

promise.return_value(expression);
goto final_suspend;

2. Void Return

When co_return; is evaluated without an operand, the compiler translates it to:

promise.return_void();
goto final_suspend;

When co_return expression; is evaluated and the expression has a type of void, the C++ standard mandates that the void expression must be evaluated before promise.return_void() is called. The compiler conceptually translates this to:

expression;
promise.return_void();
goto final_suspend;

Execution Flow

When a co_return statement is encountered, the coroutine executes the following sequence:

1. Promise Mutation: The compiler invokes either promise.return_value(<expr>) or promise.return_void(), evaluating any void expressions beforehand if applicable.
2. Local Destruction: All variables with automatic storage duration in the coroutine’s local scope are destroyed in reverse order of their construction.
3. Final Suspension: Control is transferred to the final suspension point. The compiler implicitly executes co_await promise.final_suspend();. This allows the coroutine to either suspend one last time (keeping the state alive for the caller to read the result) or destroy itself immediately.

Compiler Constraints and Rules

• Mutual Exclusion with return: A function cannot contain both return and co_return statements. Using a standard return inside a coroutine results in a compilation error.
• Promise Type Requirements: Under C++20 semantics, the definition of a coroutine is ill-formed if its promise type declares both return_void and return_value. This rule applies to the mere definition of the coroutine, regardless of whether any co_return statements are actually present in the coroutine body.
• Implicit co_return: If execution reaches the end of a coroutine body without encountering a co_return statement, the compiler evaluates the promise type. If promise.return_void() is a valid expression (e.g., it is declared, accessible, and satisfies overload resolution), the compiler implicitly injects co_return; at the end of the body. If promise.return_void() is not a valid expression, flowing off the end of the coroutine results in undefined behavior.
• Main Function: The main function cannot be a coroutine; therefore, co_return cannot be used inside main.

Master C++ with Deep Grasping Methodology!

Learn More