P3367R5: constexpr coroutines

Standard transformation

Simple generator which take a value, yield it and later yield value².

auto simple(T start) -> std::generator<T> {
	co_yield start;
	auto quad = start * start;
	co_yield quad;
}

This code is current transformed into:

auto simple(T start) -> std::generator<T> {
	return std::generator<T>{ coroutine-frame {
		std::generator<T>::promise_type _promise{};
		auto start = start; // copy arguments
		try {
			co_await _promise.initial_suspend();
			co_await _promise.yield_value(start);
			auto quad = start * start;
			co_await _promise.yield_value(quad);
			// body
		} catch (...) {
			if (!initial-await-resume-called) {
				throw;
			}
			_promise.promise.unhandled_exception();
		}
		// final-suspend:
		 co_await promise.final_suspend() ;
	}};
}

As you can see, it's all just transformation. A function into a coroutine body explicitly managing life-time of a promise type, and co_yield into co_await. Compiler is already doing a lot of transformation in frontend. This proposed implementation strategy is just making a bit more transformations.

Transformation into void-style continuation

Any coroutine can be transformed into a set of void returning functions:

coroutine simple(T argument) {
	auto result = co_await normal_function(argument);
	co_return result;
}

With resulting code looking somehow like this:

struct coroutine_state_base {
	// where to jump
	void (*resume_point)(coroutine_state_base *) = nullptr;
};	

// unique type per each coroutine function
struct __coroutine_state: coroutine_state_base {
	// all arguments here...
	T argument;
	
	// promise type
	coroutine::promise_type promise;

	// all variables / temporaries which can survive suspension
	initial_awaiter initial_suspend_result;
	final_awaiter final_suspend_result;
	decltype(normal_function(argument)) tmp;
};

constexpr coroutine simple(T argument) { // <------------- starting point
	// create state
	auto * state = new __coroutine_state{};
	
	// copy arguments
	state->argument = argument;
	
	// construct promise
	new (&state->promise) coroutine::promise_type{...};
	
	// construct result
	auto result = state->promise.get_return_object();
	
	// call (jump-into) coroutine body
	simple_start(state);
	
	// return result object with coroutine handle (usually)
	return result;
}

constexpr void simple_start(coroutine_state_base * vstate) {
	auto * state = static_cast<__coroutine_state *>(vstate);
	
	// INITIAL SUSPEND
	state->initial_suspend_result = state->promise.initial_suspend()
	if (!state->initial_suspend_result.await_ready()) {
		state->resume_point = &simple_after_init_suspend;
		
		// tail-recursion jump to next coroutine or continue
		NEXT-COROUTINE(state->initial_suspend_result.await_suspend(std::coroutine_handle{state}));
	}
	return simple_after_init_suspend(state); // tail-recursion
}

constexpr void simple_after_init_suspend(coroutine_state_base * vstate) {
	auto * state = static_cast<__coroutine_state *>(vstate);
	
	// BEFORE CUSTOM CO_AWAIT
	try {
		(void)state->initial_suspend.await_resume();
		std::destroy_at(&state->initial_suspend_result); // lifetime of temporary must be destroyed
		
		// normal body
		state->tmp = normal_function(state->argument);
		
		if (!state->tmp.await_ready()) {
			state->resume_point = &simple_after_first_await;
			
			// tail-recursion jump to next coroutine or continue
			NEXT-COROUTINE(state->tmp.await_suspend(std::coroutine_handle{state}));
		}
		
		return simple_after_first_await(state);
	} catch (...) {
		std::destroy_at(&state->tmp);
		state->promise.unhandled_exception();
		return simple_final_suspend(state);
	}
}

constexpr void simple_after_first_await(coroutine_state_base * vstate) {
	auto * state = static_cast<__coroutine_state *>(vstate);
	
	// RESUMED or just jumped after CUSTOM CO_AWAIT
	try {
		// get result (which doesn't survive suspension, so it can be put here on stack)
		auto result = state->tmp.await_resume();
		
		// co_return result
		state->promise.return_value(result); 
		
		// end of scope for state->tmp
		std::destroy_at(&state->tmp);
		
	} catch (...) {
		std::destroy_at(&state->tmp);
		state->promise.unhandled_exception();
	}
	
	// jump to final suspend
	return simple_final_suspend(state);
}

constexpr void simple_final_suspend(coroutine_state_base * vstate) {
	auto * state = static_cast<__coroutine_state *>(vstate);
	
	// FINAL SUSPEND
	state->final_suspend_result = state->promise.final_suspend();
	if (!state->final_suspend_result.await_ready()) {
		state->resume_point = nullptr;
		
		// tail-recursion jump to next coroutine or continue
		NEXT-COROUTINE(state->final_suspend_result.await_suspend(std::coroutine_handle{state}));
	}
	// destruction of state after final-suspend
	delete &state;
	// no-return ... which will return us to our resumer
}

Whole transformation is just changing all edges to standalone void returning function between which can be jumped with a tail recursion. Each .await_suspend(coroutine_handle) can return handle to next coroutine, boolean with information if it should be a suspend or not, or just void, which means simple suspend.

// NEXT-COROUTINE(EXPR) is:
using type = decltype(EXPR);                                                        
if constexpr (std::is_void_v<type>) {                                         
	EXPR;                                                                             
	return; // return to caller                                                       
} else if constexpr (std::same_as<type, bool>) {                              
	if (EXPR) {                                                                       
		return; // return to caller                                                     
	}                                                                                 
	// continue in coroutine                                                          
} else if constexpr (std::convertible_to<std::coroutine_handle<void>>) {
	auto * next_state = static_cast<coroutine_state_base *>(E(XPR).address());                                                          
	return next_state->resume_point(next_state); // tail-recursion
}                                                                                   

Most of the transformation is lifetime handling and splitting at each co_await. The suspend transformation is already part of compilers so await_ready(), await_suspend(std::coroutine_handle), await_resume() is already part of each compiler.

Loops transformation

constexpr coroutine loops() noexcept {
		while (co_await check()) {
			another_function();
		}
	}

Code above is transformed into:

constexpr void loops_main(coroutine_state_base * vstate) noexcept {
	// initial suspend skipped for readability
		
	auto * state = static_cast<__coroutine_state *>(vstate);
	state->tmp = check();
	if (!state->tmp.await_ready()) {
		state->resume_point = &loops_main_body;
		NEXT-COROUTINE(state->tmp.await_suspend(std::coroutine_handle{state}));
	}
	return loops_main_body(state); // tail-recursion
}

constexpr void loops_main_body(coroutine_handle_base * vstate) noexcept {
	auto * state = static_cast<__coroutine_state *>(vstate);
	if (state->tmp.await_resume()) {
		another_function();
		return loops_main(state); // tail-recursion
	}
	std::destroy_at(&state->tmp);
	return loops_final_suspend(state);
}

Tail-recursion

To implement constexpr coroutines with the AST transformation a tail recursion is needed to be supported in constant evaluator.