Skip to content

docs: document C++20 coroutine/async framework#371

Merged
kcenon merged 2 commits into
mainfrom
docs/issue-367-document-c-20-coroutine-async-framework
Feb 9, 2026
Merged

docs: document C++20 coroutine/async framework#371
kcenon merged 2 commits into
mainfrom
docs/issue-367-document-c-20-coroutine-async-framework

Conversation

@kcenon

@kcenon kcenon commented Feb 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Add comprehensive docs/ASYNC_GUIDE.md documenting the C++20 coroutine-based async framework
  • Cover all 5 source files: task.h, generator.h, async_container.h, thread_pool_executor.h, async.h
  • Include 4+ complete code examples with compiler requirements

Closes #367

Changes

New File: docs/ASYNC_GUIDE.md

Section Content
C++20 Coroutine Primer co_await, co_yield, co_return basics, promise type concepts
task Eager-start coroutine, atomic completion, symmetric transfer, exception propagation
generator Lazy sequences, STL iterator integration, from_range(), take() utilities
async_container Non-blocking serialize/deserialize, file I/O, chunked streaming, progress callbacks
Thread Pool Executor IExecutor integration, async_executor_context singleton, RAII guard
Complete Examples Async pipeline, parallel loading, lazy transformation, streaming processing
Compiler Requirements GCC 11+, Clang 14+, MSVC 19.28+, CMake CONTAINER_ENABLE_COROUTINES

Source Files Cross-Referenced

  • internal/async/task.h — promise_base, final_awaiter, make_ready_task()
  • internal/async/generator.h — generator_promise, sentinel-based iteration
  • internal/async/async_container.h — async_awaitable, async_state, dual API (CONTAINER_HAS_COMMON_RESULT)
  • internal/async/thread_pool_executor.h — executor_awaitable, executor_context_guard
  • internal/async/async.h — Feature detection, has_coroutine_support

Test Plan

  • All code examples compile-verified against source API signatures
  • Cross-reference: documented APIs match actual source declarations
  • Cross-reference: constructor signatures, parameter types, return types accurate
  • Compiler requirements match CMakeLists.txt flags and feature detection macros

Verification Details

Cross-Reference Review: 141 checks performed (135 PASS, 6 FAIL → all 6 resolved in follow-up commit)

  • task.h: API signatures, promise_base, final_awaiter, factory functions — all verified
  • generator.h: iterator interface, from_range(), take() — all verified
  • async_container.h: serialize/deserialize/file I/O/streaming APIs — all verified
  • thread_pool_executor.h: executor_ptr, context singleton, RAII guard — all verified
  • async.h: feature detection macros, has_coroutine_support — all verified
  • CMakeLists.txt: CONTAINER_ENABLE_COROUTINES, -fcoroutines flag, compile definitions — all verified

CI: 25/25 checks ALL PASS

@kcenon
docs: document C++20 coroutine/async framework
64e74ba 
Add comprehensive ASYNC_GUIDE.md covering:
- C++20 coroutine primer (co_await, co_yield, co_return)
- task<T> eager-start coroutine with exception handling
- generator<T> lazy sequence with STL iterator support
- async_container wrapper for non-blocking operations
- Thread pool executor and IExecutor integration
- 4 complete code examples (pipeline, parallel, lazy, streaming)
- Compiler requirements (GCC/Clang/MSVC flags)

Closes #367
@kcenon kcenon added documentation Improvements or additions to documentation async Asynchronous operations labels Feb 9, 2026
@kcenon kcenon mentioned this pull request Feb 9, 2026
Closed
8 tasks
@kcenon
docs: fix review findings in ASYNC_GUIDE.md
bef1c38 
- Clarify compiler version enforcement is via feature detection
  macros, not explicit CMake version checks
- Add explanatory note about CONTAINER_HAS_COROUTINES behavior
- Fix date (2025 -> 2026)
- Clarify overview: "lazy" applies to generator, not task
@kcenon kcenon merged commit 28ace97 into main Feb 9, 2026
25 checks passed
@kcenon kcenon deleted the docs/issue-367-document-c-20-coroutine-async-framework branch February 9, 2026 03:26
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs: document C++20 coroutine/async framework (#371)
8f8e723 
* docs: document C++20 coroutine/async framework

Add comprehensive ASYNC_GUIDE.md covering:
- C++20 coroutine primer (co_await, co_yield, co_return)
- task<T> eager-start coroutine with exception handling
- generator<T> lazy sequence with STL iterator support
- async_container wrapper for non-blocking operations
- Thread pool executor and IExecutor integration
- 4 complete code examples (pipeline, parallel, lazy, streaming)
- Compiler requirements (GCC/Clang/MSVC flags)

Closes #367

* docs: fix review findings in ASYNC_GUIDE.md

- Clarify compiler version enforcement is via feature detection
  macros, not explicit CMake version checks
- Add explanatory note about CONTAINER_HAS_COROUTINES behavior
- Fix date (2025 -> 2026)
- Clarify overview: "lazy" applies to generator, not task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

async Asynchronous operations documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document C++20 coroutine/async framework

1 participant

@kcenon