Coroutines: coroutine.hpp
C++20+ only, GCC/Clang only (on older standards the header is empty and
RELOCO_HAS_COROUTINES is 0). No exceptions: failures travel as
reloco::result, and an exception escaping a coroutine traps.
#include <reloco/coroutine.hpp>
// Fallible helper returning a plain result<int>.
reloco::result<int> parse(int v);
// The coroutine frame is always allocated from reloco::default_allocator();
// there is no per-coroutine allocator parameter.
reloco::task<int> work(int v) {
// co_await on a result<U> yields U; on error the coroutine ends with that
// error (like RELOCO_TRY), and its locals are destroyed normally.
int parsed = co_await parse(v);
// Awaiting another task yields its result<T>; await that again to unwrap/propagate.
auto inner = co_await work(parsed - 1);
int sub = co_await std::move(inner);
// co_return a value, or an error via reloco::unexpected (task<void> uses
// `co_await reloco::unexpected(e)` instead).
if (sub > 100)
co_return reloco::unexpected(reloco::error::out_of_range);
co_return sub;
}
// Drive a top-level task: tasks are lazy, so resume() starts it. Resume again
// whenever an awaitable it is blocked on completes, until done().
auto t = work(5);
t.resume();
if (t.done()) {
reloco::result<int> r = t.take(); // value or error, taken once
}
Notes
- Allocation failure is not fatal: the returned task is already
done()andtake()yieldserror::allocation_failed; awaiting it propagates it. - Frame allocator is
reloco::default_allocator(); choose it once per platform with theRELOCO_DEFAULT_ALLOCATOR_CUSTOMhook. Per-coroutine allocators are intentionally unsupported: they require a variadic placementoperator new, which GCC reports as a bogus-Wmismatched-new-deleteagainst the plainoperator deletethe compiler calls on its cleanup path, and the only alternative (a thread-local “current allocator”) is unavailable on embedded targets. - Over-aligned locals (
alignasabovemax_align_talive across a suspension) are unsupported: neither GCC nor Clang requests an aligned frame allocation (they never calloperator new(size_t, align_val_t)for coroutine frames), so such a local would not be correctly aligned. - Write coroutines as functions, not capturing lambdas: a temporary lambda dies before the frame that refers to it.
- Tested with Clang 24 and GCC 15 (ASan/UBSan clean).