Coroutine-based fiber for modern C++20. More...

#include <coroutine>
#include <utility>
#include <stdexcept>

Classes
struct	jh::async::resume_t
	Tag type used to trigger a `co_await` inside a `fiber`. More...
class	jh::async::fiber
	Coroutine-based fiber providing manual suspension and resumption. More...
struct	jh::async::fiber::promise_type

Namespaces
namespace	jh::async
	Aggregated entry point for coroutine-based asynchronous facilities.

Variables
resume_t	jh::async::resume_tag {}
	Global constant instance of `resume_t`.

Detailed Description

Coroutine-based fiber for modern C++20.

Copyright: Copyright 2025 JeongHan-Bae <mastropseudo@gmail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Full license: GitHub

Author: JeongHan-Bae <mastropseudo@gmail.com>

Overview

This file defines a lightweight coroutine-based execution unit named fiber. A fiber represents a resumable coroutine without scheduling support. Its behavior is conceptually aligned with a thread blocked on condition_variable.wait(), but with significantly lower overhead.

Design Notes

Execution occurs entirely inside the coroutine body.
All coroutine logic must be noexcept.
Any uncaught exception results in an immediate call to std::terminate().
The coroutine does not guarantee co_return or co_yield like a generator; this makes exception masking mandatory.

Usage Model

The fiber object can be resumed repeatedly using resume() until it reaches its final suspend point. The type does not integrate with an external scheduler and does not provide automatic continuation handling.

Platform Notes

The behavior of jh::async::fiber depends primarily on the compiler frontend rather than the underlying standard library implementation.

Clang

Clang's coroutine lowering is fully conforming for this use-case. Lambda-based coroutine construction behaves correctly, temporary objects are tracked properly, and fiber lifetimes remain well-defined.

GCC 14 and newer

GCC (14 and 15 tested) exhibits a frontend issue when a coroutine is produced directly from an immediately-invoked lambda:

auto f = [...]() -> jh::async::fiber {
    ...
    co_await resume_tag;
}(); // <-- problematic

In this form, GCC may mis-handle the lifetime and binding of the temporary lambda object, leading to premature destruction of the coroutine frame or dangling references during suspension. This is a frontend analysis problem, not a runtime or ABI limitation.

The safe construction pattern is:

auto make_fiber = [...]() -> jh::async::fiber {
    ...
    co_await resume_tag;
};
auto f = make_fiber(); // <-- safe

This avoids the temporary-lifetime misanalysis and ensures fully correct coroutine behavior on all tested platforms.

Summary:

Clang: fully stable for fiber usage.
GCC 14+: avoid immediately-invoked coroutine lambdas.
Use the two-step lambda construction on all GCC versions.

Version

1.4.x

Date

Classes

Namespaces