Skip to content

Commit 1aa0ebb

Browse files
loongs-zhangloongs-zhang
authored
Translate some documents (#398)
2 parents 4732cae + b503ce5 commit 1aa0ebb

15 files changed

+300
-48
lines changed

‎README_ZH.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine "解决issue的平均时间")
99
[![Percentage of issues still open](http://isitmaintained.com/badge/open/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine "仍未关闭issue的百分比")
1010

11-
`open-coroutine`是一个简单、高效、通用的有栈协程库，您可以将其用作IO线程池的性能替代，查看[为什么更好](core/docs/en/why-better.md).
11+
`open-coroutine`是一个简单、高效、通用的有栈协程库，您可以将其用作IO线程池的性能替代，查看[为什么更好](core/docs/cn/why-better.md).
1212

1313
[English](README.md) | 中文
1414

@@ -31,7 +31,7 @@
3131
- [ ]
3232
增加性能[基准测试](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);
3333
- [ ] 取消协程/任务;
34-
- [ ] 增加性能指标;
34+
- [ ] 增加性能指标监控;
3535
- [ ] 增加并发工具包;
3636
- [ ] 支持AF_XDP套接字;
3737

@@ -181,8 +181,16 @@ fn main() {
181181

182182
## ⚓ 了解更多
183183

184+
- [项目总览](core/docs/cn/overview.md)
184185
- [诞生之因](docs/cn/background.md)
185186
- [语言选择](docs/cn/why-rust.md)
187+
- [协程总览](core/docs/cn/coroutine.md)
188+
- [可伸缩栈总览](core/docs/cn/scalable-stack.md)
189+
- [Monitor总览](core/docs/cn/monitor.md)
190+
- [工作窃取总览](core/docs/cn/work-steal.md)
191+
- [有序工作窃取总览](core/docs/cn/ordered-work-steal.md)
192+
- [协程池总览](core/docs/cn/coroutine-pool.md)
193+
- [Hook总览](hook/docs/cn/hook.md)
186194

187195
[旧版文档在这](https://github.com/acl-dev/open-coroutine-docs)
188196

‎core/docs/cn/coroutine-pool.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,6 @@ sequenceDiagram
5353
participant WorkerCoroutine
5454
participant Task
5555
participant CoroutineCreator
56-
5756
Schedule Thread ->>+ CoroutinePool: CoroutinePool::try_timeout_schedule_task
5857
alt 协程池已停止
5958
CoroutinePool ->>+ Schedule Thread: 返回错误

‎core/docs/cn/monitor.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ fn main() -> std::io::Result<()> {
4444

4545
## 为什么需要抢占？
4646

47-
在调用`Coroutine::resume_with`后，协程可能会长时间占用调度线程，从而拖慢由该调度线程调度的其他协程。协程在两种情况下会长时间占用调度线程：陷入大量计算或系统调用。为了解决陷入大量计算的问题，我们引入抢占式调度，它会自动挂起长时间执行的协程，并允许其他协程执行。
47+
在调用`Coroutine::resume_with`后，协程可能会长时间占用调度线程，从而拖慢由该调度线程调度的其他协程。协程在两种情况下会长时间占用调度线程：陷入重度计算或系统调用。为了解决陷入重度计算的问题，我们引入抢占式调度，它会自动挂起长时间执行的协程，并允许其他协程执行。
4848

4949
## 什么是monitor？
5050

@@ -58,7 +58,6 @@ sequenceDiagram
5858
participant 协程
5959
participant MonitorListener
6060
participant Monitor线程
61-
6261
用户线程 ->>+ 协程: Coroutine::resume_with
6362
协程 ->>+ MonitorListener: Listener::on_state_changed
6463
MonitorListener ->>+ Monitor线程: Monitor::submit

‎core/docs/cn/ordered-work-steal.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: 有序工作窃取总览
3+
date: 2025-01-17 08:34:00
4+
author: loongs-zhang
5+
---
6+
7+
# 有序工作窃取总览
8+
9+
[English](../en/ordered-work-steal.md) | 中文
10+
11+
## 为什么需要有序工作窃取？
12+
13+
在现实世界中，总是有一些线程先完成自己的任务，而其他线程还有任务需要处理。于是，就会出现一核有难、多核围观的壮观场景。
14+
15+
<div style="text-align: center;">
16+
<img src="../../../docs/img/watching.png" width="50%">
17+
</div>
18+
19+
显然，我们不希望这种情况发生。对于空闲的线程，与其让它们围观其他线程工作，不如让它们帮助其他线程工作。此外，我们希望根据优先级执行任务，优先级越高，任务越早被执行。
20+
21+
## 什么是有序工作窃取队列？
22+
23+
有序工作窃取队列由一个全局队列和多个本地队列组成，全局队列是无界的，而本地队列是一个有界的`SkipList`集合。为了确保高性能，本地队列的数量通常等于线程的数量。值得一提的是，如果所有线程都优先处理本地任务，可能会出现一种极端情况，即共享队列上的任务永远没有机会被调度。为了避免这种不平衡，参考goroutine的设计，每次线程从本地队列调度了60个任务后，强制从共享队列中弹出`优先级最高的任务`。
24+
25+
## `push`的工作原理
26+
27+
```mermaid
28+
flowchart TD
29+
Cond{本地队列是否已满?}
30+
PS[将任务推入本地队列]
31+
PTG[将本地队列中一半的低优先级任务推入全局队列]
32+
PG[将任务推入全局队列]
33+
push --> Cond
34+
Cond -- 否 --> PS
35+
Cond -- 是 --> PTG --- PG
36+
```
37+
38+
## `pop`的工作原理
39+
40+
```mermaid
41+
flowchart TD
42+
Cond1{本地队列中是否有任务?}
43+
Cond2{其他本地队列中是否有任务?}
44+
Cond3{全局队列中是否有任务?}
45+
PS[弹出优先级最高的任务]
46+
ST[从其他本地队列窃取高优先级任务]
47+
PF[未找到任务]
48+
pop --> Cond1
49+
Cond1 -- 是 --> PS
50+
Cond1 -- 否 --> Cond2
51+
Cond2 -- 是 --> ST --> PS
52+
Cond2 -- 否 --> Cond3
53+
Cond3 -- 是 --> PS
54+
Cond3 -- 否 --> PF
55+
```

‎core/docs/cn/overview.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: open-coroutine总览
3+
date: 2025-01-10 08:24:00
4+
author: loongs-zhang
5+
---
6+
7+
# open-coroutine总览
8+
9+
[English](../en/overview.md) | 中文
10+
11+
[![crates.io](https://img.shields.io/crates/v/open-coroutine.svg)](https://crates.io/crates/open-coroutine)
12+
[![docs.rs](https://img.shields.io/badge/docs-release-blue)](https://docs.rs/open-coroutine)
13+
[![LICENSE](https://img.shields.io/github/license/acl-dev/open-coroutine.svg?style=flat-square)](https://github.com/acl-dev/open-coroutine/blob/master/LICENSE-APACHE)
14+
[![Build Status](https://github.com/acl-dev/open-coroutine/workflows/CI/badge.svg)](https://github.com/acl-dev/open-coroutine/actions)
15+
[![Codecov](https://codecov.io/github/acl-dev/open-coroutine/graph/badge.svg?token=MSM3R7CBEX)](https://codecov.io/github/acl-dev/open-coroutine)
16+
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine "Average time to resolve an issue")
17+
[![Percentage of issues still open](http://isitmaintained.com/badge/open/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine "Percentage of issues still open")
18+
19+
`open-coroutine`是一个简单、高效、通用的有栈协程库，您可以将其用作IO线程池的性能替代，查看[为什么更好](core/docs/en/why-better.md).
20+
21+
- [诞生之因](../../../docs/cn/background.md)
22+
- [语言选择](../../../docs/cn/why-rust.md)
23+
- [为什么更好](../cn/why-better.md)
24+
- [快速开始](../../../README_ZH.md)
25+
- [协程总览](../cn/coroutine.md)
26+
- [可伸缩栈总览](../cn/scalable-stack.md)
27+
- [Monitor总览](../cn/monitor.md)
28+
- [工作窃取总览](../cn/work-steal.md)
29+
- [有序工作窃取总览](../cn/ordered-work-steal.md)
30+
- [协程池总览](../cn/coroutine-pool.md)
31+
- [Hook总览](../../../hook/docs/cn/hook.md)

‎core/docs/cn/scalable-stack.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,13 @@ fn main() -> std::io::Result<()> {
4141

4242
协程的默认栈大小为128KB，这对于大多数场景来说已经足够，但仍有一些场景不适用，例如递归算法。可扩展栈允许在程序中标注可能需要更大栈的扩容点。如果栈达到其限制，则会溢出到堆中。
4343

44-
## How it works
44+
## 工作原理
4545

4646
```mermaid
4747
flowchart TD
48-
Cond1{在协程中}
49-
Cond2{达到限制}
50-
Cond3{第一次扩容}
48+
Cond1{在协程中?}
49+
Cond2{达到限制?}
50+
Cond3{第一次扩容?}
5151
C[创建新栈]
5252
RC[在当前栈上运行]
5353
RN1[在新栈上运行]

‎core/docs/cn/why-better.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: 为什么更好
3+
date: 2025-01-10 08:28:00
4+
author: loongs-zhang
5+
---
6+
7+
# 为什么更好
8+
9+
[English](../en/why-better.md) | 中文
10+
11+
## 系统调用不会阻塞
12+
13+
首先，我们来看一下线程是如何与系统调用协作的。
14+
15+
```mermaid
16+
sequenceDiagram
17+
actor 用户线程
18+
participant 操作系统
19+
用户线程 ->>+ 用户线程: 执行
20+
alt 用户线程被阻塞
21+
用户线程 ->>+ 操作系统: 慢系统调用
22+
操作系统 ->> 用户线程: 返回
23+
end
24+
用户线程 ->>+ 用户线程: 执行
25+
```
26+
27+
如果系统调用是一个慢系统调用，例如默认阻塞的`accept`，线程将被长时间阻塞，直到操作系统返回为止，期间无法做任何事情。现在，我们来看一下 open-coroutine 是如何与系统调用协作的。
28+
29+
```mermaid
30+
sequenceDiagram
31+
actor EventLoop线程
32+
participant 协程1
33+
participant 协程2
34+
participant 被代理的系统调用
35+
participant 操作系统
36+
EventLoop线程 ->>+ 协程1: 调度
37+
alt 协程1逻辑上被阻塞
38+
协程1 ->>+ 被代理的系统调用: 慢系统调用
39+
被代理的系统调用 ->>+ 操作系统: 快系统调用
40+
操作系统 ->> 被代理的系统调用: 返回错误码
41+
被代理的系统调用 ->> 协程1: 挂起协程一段时间
42+
end
43+
协程1 ->>+ EventLoop线程: 挂起
44+
EventLoop线程 ->>+ 协程2: 调度
45+
alt 协程2逻辑上被阻塞
46+
协程2 ->>+ 被代理的系统调用: 慢系统调用
47+
被代理的系统调用 ->>+ 操作系统: 快系统调用
48+
操作系统 ->> 被代理的系统调用: 返回
49+
被代理的系统调用 ->> 协程2: 返回
50+
end
51+
协程2 ->>+ EventLoop线程: 返回
52+
EventLoop线程 ->>+ 协程1: 调度
53+
alt 协程1逻辑上被阻塞
54+
协程1 ->>+ 被代理的系统调用: 从上次暂停处恢复
55+
被代理的系统调用 ->>+ 操作系统: 快系统调用
56+
操作系统 ->> 被代理的系统调用: 返回
57+
被代理的系统调用 ->> 协程1: 返回
58+
end
59+
协程1 ->>+ EventLoop线程: 返回
60+
EventLoop线程 ->>+ EventLoop线程: 调度其他协程
61+
```
62+
63+
如你所见，`被代理的系统调用`(hook)将`慢系统调用`转换为`快系统调用`。通过这种方式，尽管`EventLoop线程`在执行系统调用时仍然会被阻塞，但阻塞时间非常短。因此，与线程模型相比，`EventLoop线程`可以在相同的时间内做更多的事情。
64+
65+
## 重度计算不会阻塞
66+
67+
其次，我们来看一下线程如何处理重度计算。
68+
69+
```mermaid
70+
sequenceDiagram
71+
actor 用户线程
72+
alt 用户线程陷入循环
73+
用户线程 ->>+ 用户线程: 执行循环
74+
end
75+
```
76+
77+
就像上面的系统调用一样，线程会一直阻塞在循环中。接下来，我们来看一下open-coroutine如何处理重度计算。
78+
79+
```mermaid
80+
sequenceDiagram
81+
actor EventLoop线程
82+
participant 协程1
83+
participant 协程2
84+
participant Monitor
85+
EventLoop线程 ->>+ 协程1: 调度
86+
alt 协程1进入循环
87+
协程1 ->>+ 协程1: 执行循环一段时间
88+
Monitor ->> 协程1: 挂起协程
89+
end
90+
协程1 ->>+ EventLoop线程: 挂起
91+
EventLoop线程 ->>+ 协程2: 调度
92+
alt 协程2进入循环
93+
协程2 ->>+ 协程2: 执行循环一段时间
94+
Monitor ->> 协程1: 挂起协程
95+
end
96+
协程2 ->>+ EventLoop线程: 挂起
97+
EventLoop线程 ->>+ 协程1: 调度
98+
alt 协程1进入循环
99+
协程1 ->>+ 协程1: 从上次暂停处恢复
100+
end
101+
协程1 ->>+ EventLoop线程: 返回
102+
EventLoop线程 ->>+ EventLoop线程: 调度其他协程
103+
```
104+
105+
`Monitor`会监控协程的执行情况，一旦发现某个协程的执行时间过长，就会强制挂起该协程。因此，现在我们甚至可以[使用一个`EventLoop线程`来执行多个循环](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/preemptive.rs)，这是单线程模型无法实现的。

‎core/docs/cn/work-steal.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: 工作窃取总览
3+
date: 2025-01-17 08:34:00
4+
author: loongs-zhang
5+
---
6+
7+
# 工作窃取总览
8+
9+
[English](../en/work-steal.md) | 中文
10+
11+
## 为什么需要工作窃取？
12+
13+
在现实世界中，总是有一些线程先完成自己的任务，而其他线程还有任务需要处理。于是，就会出现一核有难、多核围观的壮观场景。
14+
15+
<div style="text-align: center;">
16+
<img src="../../../docs/img/watching.png" width="50%">
17+
</div>
18+
19+
显然，我们不希望这种情况发生。对于空闲的线程，与其让它们围观其他线程工作，不如让它们帮助其他线程工作。
20+
21+
## 什么是工作窃取队列？
22+
23+
工作窃取队列由一个全局队列和多个本地队列组成，全局队列是无界的，而本地队列是一个有界的环形缓冲区（RingBuffer）。为了确保高性能，本地队列的数量通常等于线程的数量。值得一提的是，如果所有线程都优先处理本地任务，可能会出现一种极端情况，即共享队列上的任务永远没有机会被调度。为了避免这种不平衡，参考goroutine的设计，每次线程从本地队列调度了60个任务后，强制从共享队列中弹出一个任务。
24+
25+
## `push`的工作原理
26+
27+
```mermaid
28+
flowchart TD
29+
Cond{本地队列是否已满?}
30+
PS[将任务推入本地队列]
31+
PTG[将本地队列中一半的任务推入全局队列]
32+
PG[将任务推入全局队列]
33+
push --> Cond
34+
Cond -- 否 --> PS
35+
Cond -- 是 --> PTG --- PG
36+
```
37+
38+
## `pop`的工作原理
39+
40+
```mermaid
41+
flowchart TD
42+
Cond1{本地队列中是否有任务?}
43+
Cond2{其他本地队列中是否有任务?}
44+
Cond3{全局队列中是否有任务?}
45+
PS[弹出一个任务]
46+
ST[从其他本地队列窃取任务]
47+
PF[未找到任务]
48+
pop --> Cond1
49+
Cond1 -- 是 --> PS
50+
Cond1 -- 否 --> Cond2
51+
Cond2 -- 是 --> ST --> PS
52+
Cond2 -- 否 --> Cond3
53+
Cond3 -- 是 --> PS
54+
Cond3 -- 否 --> PF
55+
```

‎core/docs/en/coroutine-pool.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,6 @@ sequenceDiagram
6262
participant WorkerCoroutine
6363
participant Task
6464
participant CoroutineCreator
65-
6665
Schedule Thread ->>+ CoroutinePool: CoroutinePool::try_timeout_schedule_task
6766
alt the coroutine pool is stopped
6867
CoroutinePool ->>+ Schedule Thread: return error

‎core/docs/en/monitor.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@ sequenceDiagram
6565
participant Coroutine
6666
participant MonitorListener
6767
participant Monitor Thread
68-
6968
User Thread ->>+ Coroutine: Coroutine::resume_with
7069
Coroutine ->>+ MonitorListener: Listener::on_state_changed
7170
MonitorListener ->>+ Monitor Thread: Monitor::submit

0 commit comments

Comments
 (0)