Summary

Document the C++20 coroutine-based async framework in container_system, including task<T>, generator<Y>, async_container, and the thread pool executor.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

container_system includes a full C++20 coroutine framework at internal/async/ enabling asynchronous and lazy container operations. This is a cutting-edge C++20 feature that most developers are unfamiliar with, making documentation especially critical.

Source files:

• internal/async/task.h — Coroutine task type (async value)
• internal/async/generator.h — Coroutine generator type (lazy sequences)
• internal/async/async_container.h — Async-enabled container wrapper
• internal/async/thread_pool_executor.h — Executor for scheduling coroutines
• internal/async/async.h — Common async utilities

Scope (What)

Create docs/ASYNC_GUIDE.md covering:

1. C++20 Coroutine Primer

• Brief intro to C++20 coroutines for developers new to the feature
• co_await, co_yield, co_return basics
• Promise type and coroutine handle concepts

2. task (task.h)

• Purpose: Lazy async computation returning a value
• API: co_await, co_return, result retrieval
• Exception handling in tasks
• Task composition (chaining, when_all, when_any)

task<container> async_load(const std::string& path) {
    auto data = co_await read_file(path);
    co_return container::from_bytes(data);
}

3. generator (generator.h)

• Purpose: Lazy sequence generation
• API: co_yield, iteration interface
• Memory efficiency for large sequences
• Range compatibility

generator<value> iterate_values(const container& c) {
    for (const auto& [key, val] : c) {
        co_yield val;
    }
}

4. async_container (async_container.h)

• Async wrapper over container types
• Non-blocking get/set operations
• Async iteration
• Concurrent access patterns

5. Thread Pool Executor (thread_pool_executor.h)

• How coroutines are scheduled on thread pools
• Executor configuration
• Integration with thread_system (if applicable)
• Custom executor implementation

6. Complete Examples

• Async container loading and processing pipeline
• Parallel container operations with task
• Lazy transformation with generator
• Producer-consumer with async_container

7. Compiler Requirements

• Required compiler flags (-fcoroutines, etc.)
• Minimum compiler versions for coroutine support
• Known compiler-specific issues

Acceptance Criteria

• C++20 coroutine basics explained
• All 5 source files documented
• task<T> usage with examples
• generator<Y> usage with examples
• async_container usage with examples
• Thread pool executor documented
• Compiler requirements listed
• At least 4 complete code examples