Skip to content

Commit 691a635

Browse files
loongs-zhangloongs-zhang
committed
add more docs
1 parent bcfb4b7 commit 691a635

File tree

12 files changed

+299
-66
lines changed

12 files changed

+299
-66
lines changed

‎README.md‎

Lines changed: 86 additions & 4 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 "Average time to resolve an 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 "Percentage of issues still open")
1010

11-
The `open-coroutine` is a simple, efficient and generic stackful-coroutine library.
11+
The `open-coroutine` is a simple, efficient and generic stackfull-coroutine library, you can use this as a performance replacement for IO thread pools.
1212

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

@@ -25,11 +25,79 @@ English | [中文](README_ZH.md)
2525

2626
## 🕊 Roadmap
2727

28+
- [ ] add docs;
29+
- [ ] add performance [benchmark](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);
2830
- [ ] cancel coroutine/task;
2931
- [ ] add metrics;
3032
- [ ] add synchronization toolkit;
3133
- [ ] support and compatibility for AF_XDP socket;
3234

35+
## 🏠 Architecture
36+
37+
```mermaid
38+
graph TD
39+
subgraph ApplicationFramework
40+
Tower
41+
Actix-Web
42+
Rocket
43+
warp
44+
axum
45+
end
46+
subgraph MessageQueue
47+
RocketMQ
48+
Pulsar
49+
end
50+
subgraph RemoteProcedureCall
51+
Dubbo
52+
Tonic
53+
gRPC-rs
54+
Volo
55+
end
56+
subgraph Database
57+
MySQL
58+
Oracle
59+
end
60+
subgraph NetworkFramework
61+
Tokio
62+
monoio
63+
async-std
64+
smol
65+
end
66+
subgraph open-coroutine-architecture
67+
subgraph core
68+
Preemptive
69+
ScalableStack
70+
WorkSteal
71+
Priority
72+
end
73+
subgraph hook
74+
HookSyscall
75+
end
76+
subgraph macros
77+
open-coroutine::main
78+
end
79+
subgraph open-coroutine
80+
end
81+
hook -->|depends on| core
82+
open-coroutine -->|depends on| hook
83+
open-coroutine -->|depends on| macros
84+
end
85+
subgraph OperationSystem
86+
Linux
87+
macOS
88+
Windows
89+
end
90+
ApplicationFramework -->|maybe depends on| RemoteProcedureCall
91+
ApplicationFramework -->|maybe depends on| MessageQueue
92+
ApplicationFramework -->|maybe depends on| Database
93+
MessageQueue -->|depends on| NetworkFramework
94+
RemoteProcedureCall -->|depends on| NetworkFramework
95+
NetworkFramework -->|runs on| OperationSystem
96+
NetworkFramework -->|can depends on| open-coroutine-architecture
97+
Database -->|runs on| OperationSystem
98+
open-coroutine-architecture -->|runs on| OperationSystem
99+
```
100+
33101
## 📖 Quick Start
34102

35103
### step1: add dependency to your Cargo.toml
@@ -60,7 +128,9 @@ fn main() {
60128
}
61129
```
62130

63-
### create a task with priority(optional)
131+
## 🪽 Advanced Usage
132+
133+
### create a task with priority
64134

65135
```rust
66136
#[open_coroutine::main]
@@ -71,7 +141,7 @@ fn main() {
71141
}
72142
```
73143

74-
### wait until the task is completed or timed out(optional)
144+
### wait until the task is completed or timed out
75145

76146
```rust
77147
#[open_coroutine::main]
@@ -83,7 +153,7 @@ fn main() {
83153
}
84154
```
85155

86-
### scalable stack(optional)
156+
### scalable stack
87157

88158
```rust
89159
#[open_coroutine::main]
@@ -112,3 +182,15 @@ fn main() {
112182
- [Monitor Overview](core/docs/en/monitor.md)
113183

114184
[我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)
185+
186+
## 🙏 Credits
187+
188+
This crate was inspired by the following projects:
189+
190+
- [acl](https://github.com/acl-dev/acl)
191+
- [coost](https://github.com/idealvin/coost)
192+
- [golang](https://github.com/golang/go)
193+
- [stacker](https://github.com/rust-lang/stacker)
194+
- [monoio](https://github.com/bytedance/monoio)
195+
- [compio](https://github.com/compio-rs/compio)
196+
- [may](https://github.com/Xudong-Huang/may)

‎README_ZH.md‎

Lines changed: 86 additions & 4 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`是一个简单、高效、通用的有栈协程库。
11+
`open-coroutine`是一个简单、高效、通用的有栈协程库，您可以将其用作IO线程池的性能替代。
1212

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

@@ -25,11 +25,79 @@
2525

2626
## 🕊 未来计划
2727

28+
- [ ] 完善文档;
29+
- [ ] 增加性能[基准测试](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);
2830
- [ ] 取消协程/任务;
2931
- [ ] 增加性能指标;
3032
- [ ] 增加并发工具包;
3133
- [ ] 支持AF_XDP套接字;
3234

35+
## 🏠 架构设计
36+
37+
```mermaid
38+
graph TD
39+
subgraph ApplicationFramework
40+
Tower
41+
Actix-Web
42+
Rocket
43+
warp
44+
axum
45+
end
46+
subgraph MessageQueue
47+
RocketMQ
48+
Pulsar
49+
end
50+
subgraph RemoteProcedureCall
51+
Dubbo
52+
Tonic
53+
gRPC-rs
54+
Volo
55+
end
56+
subgraph Database
57+
MySQL
58+
Oracle
59+
end
60+
subgraph NetworkFramework
61+
Tokio
62+
monoio
63+
async-std
64+
smol
65+
end
66+
subgraph open-coroutine-architecture
67+
subgraph core
68+
Preemptive
69+
ScalableStack
70+
WorkSteal
71+
Priority
72+
end
73+
subgraph hook
74+
HookSyscall
75+
end
76+
subgraph macros
77+
open-coroutine::main
78+
end
79+
subgraph open-coroutine
80+
end
81+
hook -->|depends on| core
82+
open-coroutine -->|depends on| hook
83+
open-coroutine -->|depends on| macros
84+
end
85+
subgraph OperationSystem
86+
Linux
87+
macOS
88+
Windows
89+
end
90+
ApplicationFramework -->|maybe depends on| RemoteProcedureCall
91+
ApplicationFramework -->|maybe depends on| MessageQueue
92+
ApplicationFramework -->|maybe depends on| Database
93+
MessageQueue -->|depends on| NetworkFramework
94+
RemoteProcedureCall -->|depends on| NetworkFramework
95+
NetworkFramework -->|runs on| OperationSystem
96+
NetworkFramework -->|can depends on| open-coroutine-architecture
97+
Database -->|runs on| OperationSystem
98+
open-coroutine-architecture -->|runs on| OperationSystem
99+
```
100+
33101
## 📖 快速接入
34102

35103
### step1: 在你的Cargo.toml中添加依赖
@@ -60,7 +128,9 @@ fn main() {
60128
}
61129
```
62130

63-
### 创建具有优先级的任务(可选)
131+
## 🪽 进阶使用
132+
133+
### 创建具有优先级的任务
64134

65135
```rust
66136
#[open_coroutine::main]
@@ -71,7 +141,7 @@ fn main() {
71141
}
72142
```
73143

74-
### 等待任务完成或超时(可选)
144+
### 等待任务完成或超时
75145

76146
```rust
77147
#[open_coroutine::main]
@@ -83,7 +153,7 @@ fn main() {
83153
}
84154
```
85155

86-
### 扩容栈(可选)
156+
### 扩容栈
87157

88158
```rust
89159
#[open_coroutine::main]
@@ -112,3 +182,15 @@ fn main() {
112182
- [语言选择](docs/cn/why-rust.md)
113183

114184
[我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)
185+
186+
## 🙏 鸣谢
187+
188+
这个crate的灵感来自以下项目：
189+
190+
- [acl](https://github.com/acl-dev/acl)
191+
- [coost](https://github.com/idealvin/coost)
192+
- [golang](https://github.com/golang/go)
193+
- [stacker](https://github.com/rust-lang/stacker)
194+
- [monoio](https://github.com/bytedance/monoio)
195+
- [compio](https://github.com/compio-rs/compio)
196+
- [may](https://github.com/Xudong-Huang/may)

‎core/docs/en/coroutine.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,19 +49,19 @@ The above is excerpted from [corosensei](https://github.com/Amanieu/corosensei).
4949

5050
## Coroutine VS Thread
5151

52-
| | coroutine | thread |
53-
|-------------------|-----------|---------|
54-
| switch efficiency | ✅ Higher | ❌ High |
55-
| memory efficiency | KB/MB | KB/MB |
56-
| scheduled by OS | ❌ | ✅ |
57-
| stack grow | ✅ | ❌ |
52+
| | coroutine | thread |
53+
|-------------------|----------------|----------|
54+
| switch efficiency | ✅ Higher | ❌ High |
55+
| memory usage | ✅ Bytes/KB/MB | ❌ KB/MB |
56+
| scheduled by OS | ❌ | ✅ |
57+
| stack grow | ✅ | ❌ |
5858

5959
## Stackfull VS Stackless
6060

6161
| | stackfull | stackless |
6262
|-------------------|-----------|-----------|
6363
| switch efficiency | ❌ High | ✅ Higher |
64-
| memory efficiency | ❌ KB/MB | ✅ Bytes |
64+
| memory usage | ❌ KB/MB | ✅ Bytes |
6565
| limitations | ✅ Few | ❌ Many |
6666

6767
In general, if the requirements for resource utilization and switching performance are not very strict, using a
@@ -112,3 +112,5 @@ coroutines may flow between multiple threads which makes `ThreadLocal` invalid.
112112
introduce `CoroutineLocal`. It's similar to `ThreadLocal`'s approach of providing replicas, but `CoroutineLocal` has
113113
upgraded the replicas to the coroutine level, which means each coroutine has its own local variables. These local
114114
variables will be dropped together when the coroutine is dropped.
115+
116+
## [Scalable Stack Overview](scalable-stack.md)

‎core/docs/en/monitor.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ fn main() -> std::io::Result<()> {
3333
// is not enabled, it will remain stuck in a dead loop after resume.
3434
let mut coroutine: Coroutine<(), (), ()> = co!(|_, ()| { loop {} })?;
3535
assert_eq!(CoroutineState::Suspend((), 0), coroutine.resume()?);
36+
// will never reach if the preemptive feature is not enabled
3637
assert_eq!(CoroutineState::Suspend((), 0), coroutine.state());
3738
Ok(())
3839
}
@@ -43,7 +44,7 @@ fn main() -> std::io::Result<()> {
4344
The `monitor` mod implements the `preemptive` feature for open-coroutine, which allows the coroutine to be preempted
4445
when it is running for a long time.
4546

46-
## Why preempt
47+
## Why preempt?
4748

4849
After a `Coroutine::resume_with`, a coroutine may occupy the scheduling thread for a long time, thereby slowing down
4950
other coroutines scheduled by that scheduling thread. To solve this problem, we introduce preemptive scheduling, which

‎core/docs/en/overview.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## open-coroutine overview
2+
3+
[![crates.io](https://img.shields.io/crates/v/open-coroutine.svg)](https://crates.io/crates/open-coroutine)
4+
[![docs.rs](https://img.shields.io/badge/docs-release-blue)](https://docs.rs/open-coroutine)
5+
[![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)
6+
[![Build Status](https://github.com/acl-dev/open-coroutine/workflows/CI/badge.svg)](https://github.com/acl-dev/open-coroutine/actions)
7+
[![Codecov](https://codecov.io/github/acl-dev/open-coroutine/graph/badge.svg?token=MSM3R7CBEX)](https://codecov.io/github/acl-dev/open-coroutine)
8+
[![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")
9+
[![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")
10+
11+
The `open-coroutine` is a simple, efficient and generic stackfull-coroutine library, you can use this as a performance replacement for IO thread pools.
12+
13+
[//]: # (todo 增加英文版本的文档)
14+
- [Background](../../../docs/cn/background.md)
15+
- [Why rust](../../../docs/cn/why-rust.md)
16+
- [Why better]()
17+
- [Quick Start](../../../README.md)
18+
- [Coroutine Overview](../en/coroutine.md)
19+
- [Scalable Stack Overview](../en/scalable-stack.md)
20+
- [Monitor Overview](../en/monitor.md)

0 commit comments

Comments
 (0)