feat: add coro_local

Author: shuai132

.github/workflows/ci.yml

@@ -200,3 +200,9 @@ jobs:
         working-directory: build
         run: |
           ./coro_multi_thread_st${{ matrix.env.BIN_SUFFIX }}
+
+      - name: Test coro_local
+        if: always()
+        working-directory: build
+        run: |
+          ./coro_coro_local${{ matrix.env.BIN_SUFFIX }}

CMakeLists.txt

@@ -124,4 +124,8 @@ if (CORO_BUILD_TEST)
     set(TARGET_NAME ${PROJECT_NAME}_multi_thread_st)
     add_executable(${TARGET_NAME} test/coro_multi_thread.cpp)
     target_compile_definitions(${TARGET_NAME} PRIVATE -DCORO_USE_SINGLE_THREAD)
+
+    # test coro_local
+    set(TARGET_NAME ${PROJECT_NAME}_coro_local)
+    add_executable(${TARGET_NAME} test/coro_local.cpp)
 endif ()

README.md

@@ -27,6 +27,7 @@ A lightweight C++20 coroutine library with async tasks, concurrency control, and
     - [wait_group](#wait_group)
     - [latch](#latch)
     - [event](#event)
+- [Coroutine-Local Storage](#coroutine-local-storage)
 - [Callback to Coroutine](#callback-to-coroutine)
 - [Configuration Options](#configuration-options)
 - [Building Tests](#building-tests)
@@ -122,6 +123,8 @@ I have also learned about some well-known C++20 coroutine open-source libraries,
 | `coro::executor_poll`                        | Polling based executor                                |
 | `coro::current_executor()`                   | Get current executor                                  |
 | `coro::callback_awaiter<T>`                  | Convert callback-style APIs to coroutines             |
+| `coro::coro_local<T>`                        | Coroutine-local storage (like thread_local)           |
+| `coro::inherit_coro_local()`                 | Inherit parent coroutine's local storage              |
 
 ## Features
 
@@ -139,6 +142,7 @@ I have also learned about some well-known C++20 coroutine open-source libraries,
 - 📦 **Embedded Support**: Compatible with MCU and embedded platforms
 - 🧩 **Extended Synchronization Primitives**: Additional synchronization tools including condition variables, events,
   latches, semaphores, and wait groups
+- 🗂️ **Coroutine-Local Storage**: Thread-local-like storage scoped to coroutines with inheritance support
 
 ## Requirements
 
@@ -692,6 +696,136 @@ async<void> setter() {
 }
 ```
 
+## Coroutine-Local Storage
+
+Coroutine-local storage provides thread-local-like storage scoped to coroutines. Each `coro_local<T>` instance acts as a
+unique key for storing values, similar to `thread_local` but for coroutines.
+
+### Basic Usage
+
+```cpp
+#include "coro/coro_local.hpp"
+
+// Define a storage key (like thread_local, typically static)
+static coro::coro_local<int> request_id;
+static coro::coro_local<std::string> user_name;
+
+async<void> process_request() {
+    // Set value for current coroutine
+    co_await request_id.set(42);
+    co_await user_name.set("Alice");
+
+    // Get value (returns default-constructed T if not set)
+    int id = co_await request_id.get();
+    std::string name = co_await user_name.get();
+
+    std::cout << "Processing request " << id << " for " << name << std::endl;
+}
+```
+
+### API Reference
+
+```cpp
+coro::coro_local<T> storage;
+
+// Set value for current coroutine
+co_await storage.set(value);
+
+// Get value (returns default T{} if not set)
+T value = co_await storage.get();
+
+// Get as optional (returns std::nullopt if not set)
+std::optional<T> opt = co_await storage.get_optional();
+
+// Get pointer (returns nullptr if not set)
+T* ptr = co_await storage.get_ptr();
+
+// Check if value exists
+bool exists = co_await storage.has();
+
+// Erase the value
+co_await storage.erase();
+```
+
+### Inheritance from Parent Coroutine
+
+Child coroutines can inherit values from their parent coroutine. By default, child coroutines can read parent values.
+Use `inherit_coro_local()` to enable copy-on-write semantics where modifications are local to the child.
+
+```cpp
+static coro::coro_local<int> context_id;
+
+async<void> parent_coro() {
+    co_await context_id.set(100);
+
+    // Child coroutine can read parent's value
+    auto child = []() -> async<void> {
+        int id = co_await context_id.get();
+        std::cout << "Child sees: " << id << std::endl;  // Prints: 100
+        co_return;
+    };
+
+    co_await child();
+}
+```
+
+### Copy-on-Write Semantics
+
+Use `inherit_coro_local()` when you want the child to inherit values but have its own copy for modifications:
+
+```cpp
+async<void> parent_coro() {
+    co_await context_id.set(100);
+
+    auto child = []() -> async<void> {
+        // Enable copy-on-write inheritance
+        co_await coro::inherit_coro_local();
+
+        // Read parent's value
+        int id = co_await context_id.get();  // 100
+
+        // Modify locally (doesn't affect parent)
+        co_await context_id.set(200);
+
+        id = co_await context_id.get();  // 200
+        co_return;
+    };
+
+    co_await child();
+
+    // Parent's value is unchanged
+    int id = co_await context_id.get();  // Still 100
+}
+```
+
+### Isolation Between Concurrent Coroutines
+
+Each coroutine has its own isolated storage. Concurrent coroutines do not interfere with each other:
+
+```cpp
+async<void> concurrent_example() {
+    static coro::coro_local<int> task_id;
+
+    auto task_a = []() -> async<void> {
+        co_await task_id.set(111);
+        co_await coro::sleep(50ms);
+        int id = co_await task_id.get();  // Still 111
+        co_return;
+    };
+
+    auto task_b = []() -> async<void> {
+        co_await task_id.set(222);
+        co_await coro::sleep(50ms);
+        int id = co_await task_id.get();  // Still 222
+        co_return;
+    };
+
+    // Both tasks run concurrently with isolated storage
+    co_await coro::spawn_local(task_a());
+    co_await coro::spawn_local(task_b());
+}
+```
+
 ## Callback to Coroutine
 
 Use `callback_awaiter` to convert callback-style APIs to coroutines:

README_CN.md

@@ -27,6 +27,7 @@
     - [wait_group](#wait_group)
     - [latch](#latch)
     - [event](#event)
+- [协程本地存储](#协程本地存储)
 - [回调转协程](#回调转协程)
 - [配置选项](#配置选项)
 - [构建测试](#构建测试)
@@ -107,6 +108,8 @@
 | `coro::executor_poll`                        | 基于轮询的执行器                           |
 | `coro::current_executor()`                   | 获取当前执行器                            |
 | `coro::callback_awaiter<T>`                  | 将回调式 API 转换为协程                     |
+| `coro::coro_local<T>`                        | 协程本地存储（类似 thread_local）            |
+| `coro::inherit_coro_local()`                 | 继承父协程的本地存储                         |
 
 ## 特性
 
@@ -123,6 +126,7 @@
 - 🔍 **单元测试**：完善的单元测试和集成测试
 - 📦 **嵌入式支持**：支持 MCU 和嵌入式平台
 - 🧩 **扩展同步原语**：提供额外的同步工具，包括条件变量、事件、门闩、信号量和等待组
+- 🗂️ **协程本地存储**：类似 thread_local 的协程作用域存储，支持继承
 
 ## 要求
 
@@ -676,6 +680,135 @@ async<void> setter() {
 }
 ```
 
+## 协程本地存储
+
+协程本地存储提供了类似 `thread_local` 的存储机制，但作用域是协程。每个 `coro_local<T>` 实例作为一个唯一的键来存储值，类似于
+`thread_local`，但针对协程。
+
+### 基本用法
+
+```cpp
+#include "coro/coro_local.hpp"
+
+// 定义存储键（类似 thread_local，通常为 static）
+static coro::coro_local<int> request_id;
+static coro::coro_local<std::string> user_name;
+
+async<void> process_request() {
+    // 为当前协程设置值
+    co_await request_id.set(42);
+    co_await user_name.set("Alice");
+
+    // 获取值（如果未设置则返回默认构造的 T）
+    int id = co_await request_id.get();
+    std::string name = co_await user_name.get();
+
+    std::cout << "处理请求 " << id << "，用户 " << name << std::endl;
+}
+```
+
+### API 参考
+
+```cpp
+coro::coro_local<T> storage;
+
+// 为当前协程设置值
+co_await storage.set(value);
+
+// 获取值（如果未设置则返回默认值 T{}）
+T value = co_await storage.get();
+
+// 获取 optional（如果未设置则返回 std::nullopt）
+std::optional<T> opt = co_await storage.get_optional();
+
+// 获取指针（如果未设置则返回 nullptr）
+T* ptr = co_await storage.get_ptr();
+
+// 检查值是否存在
+bool exists = co_await storage.has();
+
+// 删除值
+co_await storage.erase();
+```
+
+### 从父协程继承
+
+子协程可以继承父协程的值。默认情况下，子协程可以读取父协程的值。使用 `inherit_coro_local()` 启用写时复制语义，使修改仅对子协程生效。
+
+```cpp
+static coro::coro_local<int> context_id;
+
+async<void> parent_coro() {
+    co_await context_id.set(100);
+
+    // 子协程可以读取父协程的值
+    auto child = []() -> async<void> {
+        int id = co_await context_id.get();
+        std::cout << "子协程看到: " << id << std::endl;  // 输出: 100
+        co_return;
+    };
+
+    co_await child();
+}
+```
+
+### 写时复制语义
+
+当你希望子协程继承值但拥有自己的副本进行修改时，使用 `inherit_coro_local()`：
+
+```cpp
+async<void> parent_coro() {
+    co_await context_id.set(100);
+
+    auto child = []() -> async<void> {
+        // 启用写时复制继承
+        co_await coro::inherit_coro_local();
+
+        // 读取父协程的值
+        int id = co_await context_id.get();  // 100
+
+        // 本地修改（不影响父协程）
+        co_await context_id.set(200);
+
+        id = co_await context_id.get();  // 200
+        co_return;
+    };
+
+    co_await child();
+
+    // 父协程的值保持不变
+    int id = co_await context_id.get();  // 仍然是 100
+}
+```
+
+### 并发协程之间的隔离
+
+每个协程都有自己独立的存储空间。并发协程之间互不干扰：
+
+```cpp
+async<void> concurrent_example() {
+    static coro::coro_local<int> task_id;
+
+    auto task_a = []() -> async<void> {
+        co_await task_id.set(111);
+        co_await coro::sleep(50ms);
+        int id = co_await task_id.get();  // 仍然是 111
+        co_return;
+    };
+
+    auto task_b = []() -> async<void> {
+        co_await task_id.set(222);
+        co_await coro::sleep(50ms);
+        int id = co_await task_id.get();  // 仍然是 222
+        co_return;
+    };
+
+    // 两个任务并发运行，存储空间相互隔离
+    co_await coro::spawn_local(task_a());
+    co_await coro::spawn_local(task_b());
+}
+```
+
 ## 回调转协程
 
 使用 `callback_awaiter` 将回调式 API 转换为协程：

include/coro/coro.hpp

@@ -11,6 +11,11 @@
 
 #include "executor.hpp"
 
+// Forward declaration for coro_local support
+namespace coro::detail {
+struct coro_local_map;
+}
+
 /// options
 // #define CORO_DISABLE_EXCEPTION
 
@@ -177,6 +182,10 @@ struct awaitable_promise : awaitable_promise_value<T>, debug_coro_promise {
   std::coroutine_handle<> parent_handle_{};
   executor* executor_ = nullptr;       // from bind_executor or inherit from caller
   awaitable<T>* awaitable_ = nullptr;  // have awaitable lived or detached
+
+  // Local storage support
+  std::shared_ptr<detail::coro_local_map> local_storage_;
+  std::shared_ptr<detail::coro_local_map> parent_local_storage_;  // for inheritance
 };
 
 template <typename T>
@@ -239,6 +248,8 @@ struct awaitable {
     if (!current_coro_handle_.promise().executor_) {
       current_coro_handle_.promise().executor_ = h.promise().executor_;
     }
+    // inherit local storage from parent coroutine
+    current_coro_handle_.promise().parent_local_storage_ = h.promise().local_storage_;
     current_coro_handle_.promise().parent_handle_ = h;
     return current_coro_handle_;
   }