Skip to content

Commit 7e99329

Browse files
loongs-zhangloongs-zhang
committed
add more docs
1 parent bcfb4b7 commit 7e99329

File tree

6 files changed

+172
-16
lines changed

6 files changed

+172
-16
lines changed

‎README.md‎

Lines changed: 72 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

@@ -30,6 +30,72 @@ English | [中文](README_ZH.md)
3030
- [ ] add synchronization toolkit;
3131
- [ ] support and compatibility for AF_XDP socket;
3232

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

35101
### step1: add dependency to your Cargo.toml
@@ -60,7 +126,9 @@ fn main() {
60126
}
61127
```
62128

63-
### create a task with priority(optional)
129+
## 🪽 Advanced Usage
130+
131+
### create a task with priority
64132

65133
```rust
66134
#[open_coroutine::main]
@@ -71,7 +139,7 @@ fn main() {
71139
}
72140
```
73141

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

76144
```rust
77145
#[open_coroutine::main]
@@ -83,7 +151,7 @@ fn main() {
83151
}
84152
```
85153

86-
### scalable stack(optional)
154+
### scalable stack
87155

88156
```rust
89157
#[open_coroutine::main]

‎README_ZH.md‎

Lines changed: 72 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

@@ -30,6 +30,72 @@
3030
- [ ] 增加并发工具包;
3131
- [ ] 支持AF_XDP套接字;
3232

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

35101
### step1: 在你的Cargo.toml中添加依赖
@@ -60,7 +126,9 @@ fn main() {
60126
}
61127
```
62128

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

65133
```rust
66134
#[open_coroutine::main]
@@ -71,7 +139,7 @@ fn main() {
71139
}
72140
```
73141

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

76144
```rust
77145
#[open_coroutine::main]
@@ -83,7 +151,7 @@ fn main() {
83151
}
84152
```
85153

86-
### 扩容栈(可选)
154+
### 扩容栈
87155

88156
```rust
89157
#[open_coroutine::main]

‎core/docs/en/coroutine.md‎

Lines changed: 7 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

‎core/docs/en/monitor.md‎

Lines changed: 1 addition & 0 deletions
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
}

‎core/docs/en/overview.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
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+
- [Monitor Overview](../en/monitor.md)

‎core/src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
clippy::separated_literal_suffix, // conflicts with clippy::unseparated_literal_suffix
5252
clippy::single_char_lifetime_names, // TODO: change lifetime names
5353
)]
54-
//! see `https://github.com/acl-dev/open-coroutine`
54+
#![doc = include_str!("../docs/en/overview.md")]
5555

5656
/// Common traits and impl.
5757
pub mod common;

0 commit comments

Comments
 (0)