实现定时等待协作式取消

Author: helantianshen

README.md

@@ -17,13 +17,13 @@
 
 > [!IMPORTANT]
 > CMP provides a lazy, single-consumer `Task<T>` / `Task<void>` and a caller-thread `RunLoop`
-> with explicit and monotonic timed scheduling. Cancellation, asynchronous I/O, and detached
-> execution are not implemented.
+> with explicit and monotonic timed scheduling. Timed waits support cooperative cancellation with
+> `std::stop_token`; asynchronous I/O and detached execution are not implemented.
 
 CMP is being built as a modern coroutine runtime and library on standard stackless C++
-coroutines. Its explicit `co_await` model now covers scheduling and monotonic timers and can grow,
-in small verified steps, toward asynchronous I/O, cancellation, and safe handling of blocking
-work.
+coroutines. Its explicit `co_await` model now covers scheduling, monotonic timers, and cancellable
+timed waits and can grow, in small verified steps, toward asynchronous I/O and safe handling of
+blocking work.
 
 ## Why CMP?
 
@@ -48,7 +48,7 @@ promise that:
 - a task is automatically equivalent to a Go goroutine;
 - an arbitrary blocking call becomes non-blocking;
 - coroutine switching is safe directly inside a signal handler;
-- M:N scheduling, work stealing, cancellation, or async I/O already exist.
+- M:N scheduling, work stealing, general cancellation propagation, or async I/O already exist.
 
 Those capabilities must be designed and verified individually. The expected direction is
 explicit async I/O awaiters, a dedicated blocking pool, and cooperative safe points.
@@ -72,10 +72,10 @@ cd examples/basic
 mcpp run
 ```
 
-The example waits for a short RunLoop timer, prints `Coroutine result: 42` from inside a
-`Task<void>` coroutine, and exits successfully. It proves that an independent mcpp package can
-resolve the path dependency, import `mcpplibs.cmp`, compose Tasks, and use timed scheduling through
-the public RunLoop.
+The example prints `Coroutine result: 42` after a short RunLoop timer, then prints
+`Coroutine cancelled` from a pre-cancelled timed wait. Both messages come from `Task<void>`
+coroutines. It proves that an independent mcpp package can import `mcpplibs.cmp`, compose Tasks,
+and use timed scheduling and cancellation through the public RunLoop.
 
 ## Current API
 
@@ -85,6 +85,7 @@ import mcpplibs.cmp;
 
 using mcpplibs::cmp::Task;
 using mcpplibs::cmp::RunLoop;
+using mcpplibs::cmp::OperationCancelled;
 
 using namespace std::chrono_literals;
 
@@ -99,9 +100,22 @@ Task<void> print_answer(RunLoop::Scheduler scheduler) {
     co_return;
 }
 
+Task<void> print_cancellation(RunLoop::Scheduler scheduler, std::stop_token token) {
+    try {
+        co_await scheduler.schedule_after(1s, token);
+    } catch (const OperationCancelled&) {
+        std::println("Coroutine cancelled");
+    }
+    co_return;
+}
+
 int main() {
     RunLoop loop {};
     loop.run(print_answer(loop.get_scheduler()));
+
+    std::stop_source source {};
+    source.request_stop();
+    loop.run(print_cancellation(loop.get_scheduler(), source.get_token()));
 }
 ```
 
@@ -123,6 +137,11 @@ never resumes it inline. Scheduler handles are copyable, but remain tied to thei
 RunLoop. Sequential `run()` calls are supported; nested or concurrent calls are rejected. A
 moved-from Task must not be awaited.
 
+The timed overloads accepting `std::stop_token` also always suspend. If cancellation wins before
+the deadline, awaiting throws `OperationCancelled`; a late stop request cannot replace an already
+queued deadline completion. The stop callback only wakes the RunLoop, so user coroutine code is
+still resumed by the thread driving `run()`. Cancellation currently performs an O(n) timer lookup.
+
 RunLoop is not a background thread and does not make blocking code asynchronous. A Task that
 suspends without arranging a future resume can leave `run()` waiting indefinitely. CMP does not
 provide automatic thread affinity: after an external awaiter resumes on another thread, explicitly
@@ -171,7 +190,8 @@ Runtime work is split into independently reviewable phases:
 1. package identity and importable-module bootstrap — implemented;
 2. coroutine task and lifetime semantics — initial `Task` implemented;
 3. a root runner and minimal single-thread scheduler — initially implemented;
-4. monotonic Timer v1 — implemented; cancellation and structured wake-up paths remain;
+4. monotonic Timer v1 and cancellable timed waits — implemented; structured task ownership and
+   wake-up paths remain;
 5. multi-worker scheduling and work stealing;
 6. asynchronous I/O integration and a blocking pool.
 

README.zh.hant.md

@@ -17,11 +17,12 @@
 
 > [!IMPORTANT]
 > CMP 已提供延遲啟動、單一消費者的 `Task<T>` / `Task<void>`，以及在呼叫執行緒運行、
-> 支援明確排程和單調時鐘定時排程的 `RunLoop`。取消、非同步 I/O 和 detached 執行尚未實作。
+> 支援明確排程和單調時鐘定時排程的 `RunLoop`。定時等待已支援基於 `std::stop_token` 的
+> 協作式取消；非同步 I/O 和 detached 執行尚未實作。
 
 CMP 計畫以標準無堆疊 C++ 協程建構現代協程執行期與函式庫。明確的 `co_await` 模型現已
-涵蓋排程和單調時鐘計時器，並將透過經過驗證的小步驟繼續探索非同步 I/O、取消，以及阻塞
-工作的安全隔離。
+涵蓋排程、單調時鐘計時器和可取消定時等待，並將透過經過驗證的小步驟繼續探索非同步 I/O，
+以及阻塞工作的安全隔離。
 
 ## 為什麼叫 CMP？
 
@@ -44,7 +45,7 @@ C++ 標準協程是語言機制，不是完整執行期。因此 CMP 不會宣
 - task 自動等同於 Go goroutine；
 - 任意阻塞呼叫會自動成為非阻塞呼叫；
 - 可以直接在訊號處理器中安全切換協程；
-- M:N 排程、work stealing、取消或非同步 I/O 已經實作。
+- M:N 排程、work stealing、通用取消傳播或非同步 I/O 已經實作。
 
 這些能力必須分別設計和驗證。預期方向是明確的非同步 I/O awaiter、專用 blocking pool
 以及協作式安全點。
@@ -68,9 +69,9 @@ cd examples/basic
 mcpp run
 ```
 
-範例會先等待一個短 RunLoop 計時器，再從 `Task<void>` 協程內部印出
-`Coroutine result: 42`，然後以成功狀態結束。它負責證明獨立 mcpp 套件能夠解析路徑相依、
-匯入 `mcpplibs.cmp`、組合 Task 並透過公開 RunLoop 使用定時排程。
+範例會在一個短 RunLoop 計時器後印出 `Coroutine result: 42`，再從預先取消的定時等待印出
+`Coroutine cancelled`；兩行都在 `Task<void>` 協程內部輸出。它負責證明獨立 mcpp 套件能夠
+匯入 `mcpplibs.cmp`、組合 Task，並透過公開 RunLoop 使用定時排程和取消。
 
 ## 目前 API
 
@@ -80,6 +81,7 @@ import mcpplibs.cmp;
 
 using mcpplibs::cmp::Task;
 using mcpplibs::cmp::RunLoop;
+using mcpplibs::cmp::OperationCancelled;
 
 using namespace std::chrono_literals;
 
@@ -94,9 +96,22 @@ Task<void> print_answer(RunLoop::Scheduler scheduler) {
     co_return;
 }
 
+Task<void> print_cancellation(RunLoop::Scheduler scheduler, std::stop_token token) {
+    try {
+        co_await scheduler.schedule_after(1s, token);
+    } catch (const OperationCancelled&) {
+        std::println("Coroutine cancelled");
+    }
+    co_return;
+}
+
 int main() {
     RunLoop loop {};
     loop.run(print_answer(loop.get_scheduler()));
+
+    std::stop_source source {};
+    source.request_stop();
+    loop.run(print_cancellation(loop.get_scheduler(), source.get_token()));
 }
 ```
 
@@ -114,6 +129,10 @@ continuation 之間直接轉移，並透過 RAII 銷毀未消費的協程框架
 任務具備執行資格，不會 inline 恢復。Scheduler 可以複製，但始終屬於建立它的 RunLoop。
 支援依序多次呼叫 `run()`，巢狀或並行呼叫會被拒絕。已經被移動的 Task 不得再次等待。
 
+接受 `std::stop_token` 的定時多載也始終暫停。如果取消先於期限獲勝，等待會拋出
+`OperationCancelled`；較晚的停止要求不能取代已經進入就緒佇列的期限完成。停止回呼只喚醒
+RunLoop，使用者協程仍由執行 `run()` 的執行緒恢復。目前取消透過 O(n) 掃描定位計時器。
+
 RunLoop 不是背景執行緒，也不會把阻塞程式碼自動變成非同步程式碼。如果 Task 暫停後沒有
 安排未來的恢復動作，`run()` 可能一直等待。CMP 不提供隱式執行緒親和：外部 awaiter 在其他
 執行緒恢復協程後，需要明確等待目標 Scheduler 才會返回對應 RunLoop。
@@ -159,7 +178,7 @@ CMP 目前不追蹤 `mcpp.lock`，`.gitignore` 明確執行這項儲存庫約定
 1. 套件識別與可匯入模組 bootstrap——已完成；
 2. 協程 task 與生命週期語意——已實作初始 `Task`；
 3. 根任務驅動器和最小單執行緒排程器——已完成初始實作；
-4. 單調時鐘 Timer v1——已實作；取消和結構化喚醒路徑仍待開發；
+4. 單調時鐘 Timer v1 和可取消定時等待——已實作；結構化任務所有權和喚醒路徑仍待開發；
 5. 多 worker 排程與 work stealing；
 6. 非同步 I/O 整合和 blocking pool。
 

README.zh.md

@@ -17,10 +17,12 @@
 
 > [!IMPORTANT]
 > CMP 已提供懒启动、单消费者的 `Task<T>` / `Task<void>`，以及在调用线程运行、支持显式
-> 调度和单调时钟定时调度的 `RunLoop`。取消、异步 I/O 和 detached 执行尚未实现。
+> 调度和单调时钟定时调度的 `RunLoop`。定时等待已支持基于 `std::stop_token` 的协作式取消；
+> 异步 I/O 和 detached 执行尚未实现。
 
-CMP 计划基于标准无栈 C++ 协程构建现代协程运行时和库。显式 `co_await` 模型现已覆盖调度和
-单调时钟定时器，并将通过经过验证的小步骤继续探索异步 I/O、取消以及阻塞工作的安全隔离。
+CMP 计划基于标准无栈 C++ 协程构建现代协程运行时和库。显式 `co_await` 模型现已覆盖调度、
+单调时钟定时器和可取消定时等待，并将通过经过验证的小步骤继续探索异步 I/O 以及阻塞工作的
+安全隔离。
 
 ## 为什么叫 CMP？
 
@@ -43,7 +45,7 @@ C++ 标准协程是语言机制，不是完整运行时。因此 CMP 不会宣
 - task 自动等同于 Go goroutine；
 - 任意阻塞调用会自动变成非阻塞调用；
 - 可以直接在信号处理器中安全切换协程；
-- M:N 调度、work stealing、取消或异步 I/O 已经实现。
+- M:N 调度、work stealing、通用取消传播或异步 I/O 已经实现。
 
 这些能力必须分别设计和验证。预期方向是显式异步 I/O awaiter、专用 blocking pool
 以及协作式安全点。
@@ -67,9 +69,9 @@ cd examples/basic
 mcpp run
 ```
 
-示例会先等待一个短 RunLoop 定时器，再从 `Task<void>` 协程内部打印
-`Coroutine result: 42`，然后以成功状态退出。它负责证明独立 mcpp 包能够解析路径依赖、
-导入 `mcpplibs.cmp`、组合 Task 并通过公共 RunLoop 使用定时调度。
+示例会在一个短 RunLoop 定时器后打印 `Coroutine result: 42`，再从预先取消的定时等待打印
+`Coroutine cancelled`；两行都在 `Task<void>` 协程内部输出。它负责证明独立 mcpp 包能够
+导入 `mcpplibs.cmp`、组合 Task，并通过公共 RunLoop 使用定时调度和取消。
 
 ## 当前 API
 
@@ -79,6 +81,7 @@ import mcpplibs.cmp;
 
 using mcpplibs::cmp::Task;
 using mcpplibs::cmp::RunLoop;
+using mcpplibs::cmp::OperationCancelled;
 
 using namespace std::chrono_literals;
 
@@ -93,9 +96,22 @@ Task<void> print_answer(RunLoop::Scheduler scheduler) {
     co_return;
 }
 
+Task<void> print_cancellation(RunLoop::Scheduler scheduler, std::stop_token token) {
+    try {
+        co_await scheduler.schedule_after(1s, token);
+    } catch (const OperationCancelled&) {
+        std::println("Coroutine cancelled");
+    }
+    co_return;
+}
+
 int main() {
     RunLoop loop {};
     loop.run(print_answer(loop.get_scheduler()));
+
+    std::stop_source source {};
+    source.request_stop();
+    loop.run(print_cancellation(loop.get_scheduler(), source.get_token()));
 }
 ```
 
@@ -113,6 +129,10 @@ continuation 之间直接转移，并通过 RAII 销毁未消费的协程帧。
 任务具备运行资格，不会 inline 恢复。Scheduler 可以复制，但始终属于创建它的 RunLoop。
 支持顺序多次调用 `run()`，嵌套或并发调用会被拒绝。已经被移动的 Task 不得再次等待。
 
+接受 `std::stop_token` 的定时重载也始终挂起。如果取消先于期限获胜，等待会抛出
+`OperationCancelled`；较晚的停止请求不能替换已经进入就绪队列的期限完成。停止回调只唤醒
+RunLoop，用户协程仍由执行 `run()` 的线程恢复。当前取消通过 O(n) 扫描定位定时器。
+
 RunLoop 不是后台线程，也不会把阻塞代码自动变成异步代码。如果 Task 挂起后没有安排未来的
 恢复动作，`run()` 可能一直等待。CMP 不提供隐式线程亲和：外部 awaiter 在其他线程恢复协程
 后，需要显式等待目标 Scheduler 才会返回对应 RunLoop。
@@ -158,7 +178,7 @@ CMP 当前不跟踪 `mcpp.lock`，`.gitignore` 明确执行这一仓库约定。
 1. 包身份和可导入模块 bootstrap——已完成；
 2. 协程 task 与生命周期语义——已实现初始 `Task`；
 3. 根任务驱动器和最小单线程调度器——已完成初始实现；
-4. 单调时钟 Timer v1——已实现；取消和结构化唤醒路径仍待开发；
+4. 单调时钟 Timer v1 和可取消定时等待——已实现；结构化任务所有权和唤醒路径仍待开发；
 5. 多 worker 调度与 work stealing；
 6. 异步 I/O 集成和 blocking pool。