What we’be been awaiting for?

`fetch` in JavaScript

async function visit_page() {

	const page = fetch("https://hanicka.net/index.html");
	const icon = fetch("https://hanicka.net/favicon.ico");

	render(await page, await icon);
	
	// ...

}

`Promise.all()` in JavaScript

async function download_page(url) {
	const page = await fetch(url);
	
	const resources = parse_html(page).map(url => fetch(url));
	
	return {content: page, resources: await Promise.all(resources)};
}

simple libcurl example

// initialization
CURL * handle = curl_easy_init();

if (handle == NULL) {
	return 1;
}

// usage
curl_easy_setopt(handle, CURLOPT_URL, "https://curl.se");
curl_easy_setopt(handle, CURLOPT_FOLLOWLOCATION, 1L);

CURLcode res = curl_easy_perform(curl);

if (res != CURLE_OK) {
	printf("curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
}

// free all resources used
curl_easy_cleanup(handle);

writing result into an object

std::string output_string{};

curl_easy_setopt(handle, CURLOPT_WRITEDATA, &output_string);

auto writer = +[](char * ptr, size_t, size_t nmemb, void * udata) -> size_t {
	auto & output = *static_cast<std::string *>(udata);
	output.append(std::string_view(ptr, nmemb));
	
	return nmemb;
};

curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, writer);

const auto res = curl_easy_perform(handle);

if (res != CURLE_OK) {
	throw std::runtime_exception{curl_easy_strerror(res)};
}

return output_string;

co_curl: RAII wrapper of CURL

namespace co_curl {
	struct easy_handle {
		easy_handle();
		explicit easy_handle(std::string_view url);
		~easy_handle();
	
		// options:
		void url(std::string_view);
		void follow_location(bool = true);
		void write_into(AppendableContainer auto & output);
		// ...
		
		result sync_perform();
		// ...
	};
}

RAII example with co_curl

auto fetch(std::string_view url) -> std::string {
	auto handle = co_curl::easy_handle{url};

	handle.follow_location();

	std::string output_string{};
	handle.write_into(output_string);

	// will block here until the request is finished
	const auto res = handle.sync_perform();

	if (!res) {
		throw std::runtime_error{res.string()};
	}
	
	return output_string;
}

Asynchronous RAII example with co_curl

auto fetch(std::string_view url) -> co_curl::promise<std::string> {
	auto handle = co_curl::easy_handle{url};

	handle.follow_location();

	std::string output_string{};
	handle.write_into(output_string);

	// will wait for the request to finish
	const auto res = co_await handle.perform();

	if (!res) {
		throw std::runtime_error{res.string()};
	}
	
	co_return output_string;
}

default std::coroutine_traits

template <typename T, typename... Args> struct std::coroutine_traits<T, Args...> 
requires requires { typename T::promise_type; }
{
	using promise_type = typename T::promise_type;
}

a customization point to select promise_type
implementing coroutine behaviour

coroutine handle

template <typename Promise = void> struct std::coroutine_handle {
	void destroy();
	void resume();
	
	// if coroutine was finished
	bool done();
	explicit operator bool();
	
	// only if Promise is not void
	Promise & promise() const;
	static coroutine_handle from_promise(Promise &);
	
	// useful for interacting with C api
	void * address() const;
	static coroutine_handle from_address(void *);
};

function type

template <typename T> struct function {
	struct promise_type;
	
	using handle_type = std::coroutine_handle<promise_type>;
	handle_type handle;
	
	function(handle_type h): handle{h} { }
	
	~function() {
		// destroy the coroutines once this owning object is destroyed
		handle.destroy();
	}
	
	T get();
	explicit operator T();
};

resume of a coroutine

[..., resume_point = &state1] {
	goto *resume_point;
state1:
	
	// suspend point
	resume_point = &state2;
	return; 
state2:
	
	// suspend point
	resume_point = &state3;
	return; 
state3:
}

co_await awaitable

if (!awaitable.await_ready()) {
	resume_point = &after;
	
	if constexpr (await_suspend returns void) {
		awaitable.await_suspend(current-coroutine-handle);
		return; // back to caller or resume()
	}
	else if constexpr (await_suspend returns bool) {
		if (awaitable.await_suspend(current-coroutine-handle)) {
			return; // back to caller or resume()
		}
	}
	else if constexpr (await_suspend returns coroutine-handle) {
		// somewhere else "symmetric transfer"
		goto *awaitable.await_suspend(current-coroutine-handle);
	}
}

after:
/* return */ awaitable.await_resume();

existing standard awaitables

namespace std {

	// will always suspend and go back to its caller/resumer
	struct suspend_always {
		constexpr bool await_ready() const noexcept { return false; }
		constexpr void await_suspend(std::coroutine_handle<>) const noexcept { }
		constexpr void await_resume() const noexcept { }
	};

	// will never suspend and will just continue
	struct suspend_never {
		constexpr bool await_ready() const noexcept { return true; }
		constexpr void await_suspend(std::coroutine_handle<>) const noexcept { }
		constexpr void await_resume() const noexcept { }
	};
}

template <typename T> struct function {
	struct promise_type {
		// implicit suspend points behaviour
		auto initial_suspend() const noexcept { return std::suspend_never{}; }
		auto final_suspend() const noexcept { return std::suspend_always{}; }
		
		// constructing of object referencing coroutine
		auto get_return_object() noexcept {
			return function{std::coroutine_handle<promise_type>::from_promise(*this)};
		}
		
		// it's a slideware!
		std::optional<T> result;
		std::exception_ptr exception;
		
		// called with co_return something
		void return_value(T value) {
			result = value;
		}
		
		// when there is an exception
		void unhandled_exception() {
			exception = std::current_exception();
		}
	};
	
	using handle_type = std::coroutine_handle<promise_type>;
	handle_type handle;
	
	function(handle_type h): handle{h} { }
	
	~function() {
		// this should behave as a function
		handle.destroy();
	}
	
	T get() {
		assert(handle.done());
		
		if (auto eptr = handle.promise().exception) {
			std::rethrow_exception(eptr);
		}
		
		return *handle.promise().result;
	}
	
	explicit operator T() {
		return get();
	}
};

auto divide(int a, int b) -> function<int> {  // pseudo-code!!
  return function<int>([a=a, b=b] coroutine-frame {    /* function will never suspend */    co_await promise.initial_suspend();

    try {
	    if (b == 0) {
	      throw std::invalid_argument{"division by zero"};
	    }
		
	    co_return a/b;    promise.return_value(a / b);
		    } catch (...) {      promise.unhandled_exception();    }
    /* function will always suspend */    co_await promise.final_suspend();     delete coroutine-frame;  })( /* run immediately */);}

`std::noop_coroutine()`

// will always suspend and go back to its caller/resumer
struct late_jump_selection {
	constexpr bool await_ready() const noexcept { return false; }
	
	constexpr auto await_suspend(std::coroutine_handle<> current) -> std::coroutine_handle<> const noexcept {
		if (just_continue) {
			return current;
		} else if (somewhere_else) {
			return other_coroutine_handle;
		} else /* if (back_to_caller) */ {
			return std::noop_coroutine();
		} 
	}
	
	constexpr void await_resume() const noexcept { }
}

template <typename R> struct promise {
	struct promise_type;
	using handle_type = std::coroutine_handle<promise_type>;
	
	promise(handle_type h): handle{h} { }
	promise(const promise &) = delete;
	promise(promise && other) noexcept: handle{std::exchange(other.handle, nullptr)} { }
	~promise() { if (handle) { handle.destroy(); } }
	
	promise & operator=(promise && other) noexcept {
		std::swap(handle, other.handle);
		return *this;
	}
	
	// promise<T> is also awaitable...
	bool await_ready() const noexcept {
		return handle.done();
	}
	
	auto await_suspend(std::coroutine_handle<> awaiter) {
		return handle.promise().someone_is_waiting_for_me(awaiter);
	}
	
	T await_resume() {
		if (auto eptr = handle.promise().exception) {
			std::rethrow_exception(eptr);
		}
		
		return handle.promise().get_result();
	}
};

template <typename R> struct promise::promise_type: function<R>::promise_type {
	std::coroutine_handle<> awaiter{};
	
	auto initial_suspend() noexcept {
		scheduler.inform_about_start();
		return std::suspend_never(); // will just continue
	}
	
	auto final_suspend() noexcept {
		struct custom_final_suspend {
			promise_type & promise;
			
			constexpr bool await_ready() const noexcept { return false; }
			constexpr void await_resume() const noexcept { }
			auto await_suspend(std::coroutine_handle<>) noexcept {
				return scheduler.final_suspend_and_select_next(promise.awaiter);
			}
		};
		
		return custom_final_suspend{*this};
	}
	
	auto someone_is_waiting_for_me(std::coroutine_handle<> other) noexcept {
		awaiter = other; // remember whom to wake up later
		return scheduler.suspend_and_select_next();
	}
};

// auto co_curl::easy_handle::perform() -> co_curl::lazy_perform;
// auto r = co_await handle.perform();

struct co_curl::lazy_perform {
	co_curl::easy_handle & curl_handle;
	
	constexpr bool await_ready() const noexcept {
		return false; // will always suspend
	}
	
	auto await_suspend(std::coroutine_handle<> awaiter) {
		curl_handle.associate_coroutine(awaiter);
		
		// will mark current coroutine blocked and will run something else
		return scheduler.suspend_and_select_next();
	}
	
	auto await_resume() -> co_curl::result;
};

struct scheduler_type {
	unsigned running_tasks{0};
	unsigned blocked_tasks{0};
	
	void inform_about_start() {
		++running_tasks;
	}
	
	auto final_suspend_and_select_next(std::coroutine_handle<> possible_next = nullptr) -> std::coroutine_handle<> {
		--running_tasks;
		return select_next(possible_next);
	}
	
	auto suspend_and_select_next() -> std::coroutine_handle<> {
		++blocked_tasks;
		return select_next();
	}
	
	auto select_next(std::coroutine_handle<> possible_next = nullptr)  -> std::coroutine_handle<> {
		if (possible_next) { // (direct awaiter in final_suspend)
			--blocked_tasks;
			return possible_next;
			
		}
		
		if (running_tasks != blocked_tasks) {
			// when whole call-tree is not blocked yet, backtrack and traverse until blocked
			return std::noop_coroutine(); 
			
		}
		
		std::coroutine_handle<> completed = complete_io_and_return_coroutine();
		--blocked;
		return completed;
	}
	
	auto complete_io_and_return_coroutine() -> std::coroutine_handle<>;
};