From b02d39cee49f9f16e4fc4e4234b4cf824faa9e77 Mon Sep 17 00:00:00 2001 From: dragon-zhang Date: Mon, 10 Mar 2025 15:45:15 +0800 Subject: [PATCH] Translate some documents --- core/docs/cn/coroutine-pool.md | 2 +- core/docs/cn/monitor.md | 80 ++++++++++++++++++++++++++++++++++ core/docs/en/coroutine-pool.md | 2 +- core/docs/en/monitor.md | 23 +++++----- core/docs/en/why-better.md | 8 ++-- 5 files changed, 98 insertions(+), 17 deletions(-) create mode 100644 core/docs/cn/monitor.md diff --git a/core/docs/cn/coroutine-pool.md b/core/docs/cn/coroutine-pool.md index 84b1fe44..3c3c03c4 100644 --- a/core/docs/cn/coroutine-pool.md +++ b/core/docs/cn/coroutine-pool.md @@ -48,7 +48,7 @@ fn main() -> std::io::Result<()> { ```mermaid sequenceDiagram - Actor Schedule Thread + actor Schedule Thread participant CoroutinePool participant WorkerCoroutine participant Task diff --git a/core/docs/cn/monitor.md b/core/docs/cn/monitor.md new file mode 100644 index 00000000..bbcf3966 --- /dev/null +++ b/core/docs/cn/monitor.md @@ -0,0 +1,80 @@ +--- +title: Monitor总览 +date: 2025-01-02 08:35:00 +author: loongs-zhang +--- + +# Monitor总览 + +[English](../en/monitor.md) | 中文 + +## 支持范围 + +`preemptive`特性目前支持以下targets： + +| | ELF (Linux, BSD, bare metal, etc) | Darwin (macOS, iOS, etc) | Windows | +|---------------|-----------------------------------|--------------------------|---------| +| `x86_64` | ✅ | ✅ | ❌ | +| `x86` | ✅ | ❌ | ❌ | +| `AArch64` | ✅ | ✅ | ❌ | +| `ARM` | ✅ | ❌ | ❌ | +| `RISC-V` | ✅ | ❌ | ❌ | +| `LoongArch64` | ✅ | ❌ | ❌ | + +✅ 已测试且稳定；⚠️ 已测试但不稳定；❌ 不支持。 + +⚠️ 如果你想直接在`open-coroutine-core`中使用`preemptive`特性，你必须学习[Hook总览](../../../hook/docs/cn/hook.md)。 + +## 使用方法 + +```rust +use open_coroutine_core::co; +use open_coroutine_core::common::constants::CoroutineState; +use open_coroutine_core::coroutine::Coroutine; + +fn main() -> std::io::Result<()> { + // 模拟最极端的死循环，如果未启用preemptive特性，协程恢复后将一直卡在死循环中 + let mut coroutine: Coroutine<(), (), ()> = co!(|_, ()| { loop {} })?; + assert_eq!(CoroutineState::Suspend((), 0), coroutine.resume()?); + // 如果未启用抢占特性，将永远不会到达此处 + assert_eq!(CoroutineState::Suspend((), 0), coroutine.state()); + Ok(()) +} +``` + +## 为什么需要抢占？ + +在调用`Coroutine::resume_with`后，协程可能会长时间占用调度线程，从而拖慢由该调度线程调度的其他协程。协程在两种情况下会长时间占用调度线程：陷入大量计算或系统调用。为了解决陷入大量计算的问题，我们引入抢占式调度，它会自动挂起长时间执行的协程，并允许其他协程执行。 + +## 什么是monitor？ + +`monitor`是open-coroutine-core的一个模块，它实现了`preemptive`特性，这允许协程在长时间运行后被抢占。 + +## 工作原理 + +```mermaid +sequenceDiagram + actor 用户线程 + participant 协程 + participant MonitorListener + participant Monitor线程 + + 用户线程 ->>+ 协程: Coroutine::resume_with + 协程 ->>+ MonitorListener: Listener::on_state_changed + MonitorListener ->>+ Monitor线程: Monitor::submit + Monitor线程 ->>+ Monitor线程: libc::sigaction + alt 发生抢占 + 协程 ->> 协程: 协程状态变为Running超过10ms + Monitor线程 ->>+ 用户线程: libc::pthread_kill + 用户线程 ->>+ 用户线程: libc::pthread_sigmask + 用户线程 ->>+ 协程: 挂起协程，具体实现可查看sigurg_handler + 协程 ->> 用户线程: 协程已被抢占 + else 未发生抢占 + 协程 ->> 协程: 协程状态变为Suspend/Syscall/Complete/Error + 协程 ->>+ MonitorListener: Listener::on_state_changed + MonitorListener ->>+ Monitor线程: Monitor::remove + Monitor线程 ->>+ MonitorListener: 返回 + MonitorListener ->>+ 协程: 返回 + 协程 ->> 用户线程: 返回 + end +``` diff --git a/core/docs/en/coroutine-pool.md b/core/docs/en/coroutine-pool.md index cc48a5c9..01c5e9b0 100644 --- a/core/docs/en/coroutine-pool.md +++ b/core/docs/en/coroutine-pool.md @@ -57,7 +57,7 @@ details: ```mermaid sequenceDiagram - Actor Schedule Thread + actor Schedule Thread participant CoroutinePool participant WorkerCoroutine participant Task diff --git a/core/docs/en/monitor.md b/core/docs/en/monitor.md index 48ccfd46..43320aea 100644 --- a/core/docs/en/monitor.md +++ b/core/docs/en/monitor.md @@ -6,6 +6,8 @@ author: loongs-zhang # Monitor Overview +English | [中文](../cn/monitor.md) + ## Supported Targets The `preemptive` feature currently supports the following targets: @@ -21,7 +23,7 @@ The `preemptive` feature currently supports the following targets: ✅ Tested and stable; ⚠️ Tested but unstable; ❌ Not supported. -⚠️ If you want to use `preemptive` feature with `open-coroutine-core` not `open-coroutine`, you must learn +⚠️ If you want to use `preemptive` feature directly in `open-coroutine-core`, you must learn [Hook Overview](../../../hook/docs/en/hook.md). ## Usage @@ -32,8 +34,8 @@ use open_coroutine_core::common::constants::CoroutineState; use open_coroutine_core::coroutine::Coroutine; fn main() -> std::io::Result<()> { - // Simulate the most extreme dead loop, if the preemptive feature - // is not enabled, it will remain stuck in a dead loop after resume. + // Simulate the most extreme dead loop, if the preemptive feature is not enabled, + // coroutine will remain stuck in a dead loop after resume. let mut coroutine: Coroutine<(), (), ()> = co!(|_, ()| { loop {} })?; assert_eq!(CoroutineState::Suspend((), 0), coroutine.resume()?); // will never reach if the preemptive feature is not enabled @@ -45,22 +47,21 @@ fn main() -> std::io::Result<()> { ## Why preempt? After a `Coroutine::resume_with`, a coroutine may occupy the scheduling thread for a long time, thereby slowing down -other coroutines scheduled by that scheduling thread. To solve this problem, we introduce preemptive scheduling, which -automatically suspends coroutines that are stuck in long-term execution and allows other coroutines to execute. - -The coroutine occupies scheduling threads for a long time in two scenarios: getting stuck in heavy computing or syscall. -The following only solves the problem of getting stuck in heavy computing. +other coroutines scheduled by that scheduling thread. The coroutine occupies scheduling threads for a long time in two +scenarios: getting stuck in heavy computing or syscall. To solve the problem of getting stuck in heavy computing, we +introduce preemptive scheduling, which automatically suspends coroutines that are stuck in long-term execution and +allows other coroutines to execute. ## What is monitor? -The `monitor` mod implements the `preemptive` feature for open-coroutine, which allows the coroutine to be preempted -when it is running for a long time. +The `monitor` is a module of open-routine-core that implements the `preemptive` feature, which allows the coroutine to +be preempted when it has been running for a long time. ## How it works ```mermaid sequenceDiagram - Actor User Thread + actor User Thread participant Coroutine participant MonitorListener participant Monitor Thread diff --git a/core/docs/en/why-better.md b/core/docs/en/why-better.md index 71ac1ac3..4f86e6e2 100644 --- a/core/docs/en/why-better.md +++ b/core/docs/en/why-better.md @@ -12,7 +12,7 @@ Firstly, let's take a look at how thread collaborate with syscall. ```mermaid sequenceDiagram - Actor User Thread + actor User Thread participant Operation System User Thread ->>+ User Thread: execute @@ -29,7 +29,7 @@ syscall. ```mermaid sequenceDiagram - Actor EventLoop Thread + actor EventLoop Thread participant Coroutine1 participant Coroutine2 participant Hooked Syscall @@ -72,7 +72,7 @@ Secondly, let's take a look at how threads handle heavy computations. ```mermaid sequenceDiagram - Actor User Thread + actor User Thread alt User Thread gets stuck in a loop User Thread ->>+ User Thread: execute loop @@ -84,7 +84,7 @@ heavy computations. ```mermaid sequenceDiagram - Actor EventLoop Thread + actor EventLoop Thread participant Coroutine1 participant Coroutine2 participant Monitor