acl-dev · loongs-zhang · Jan 8, 2025 · Jan 8, 2025
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 [![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")
 [![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")
 
-The `open-coroutine` is a simple, efficient and generic stackful-coroutine library.
+The `open-coroutine` is a simple, efficient and generic stackfull-coroutine library, you can use this as a performance replacement for IO thread pools.
 
 English | [中文](README_ZH.md)
 
@@ -25,11 +25,79 @@ English | [中文](README_ZH.md)
 
 ## 🕊 Roadmap
 
+- [ ] add docs;
+- [ ] add performance [benchmark](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);
 - [ ] cancel coroutine/task;
 - [ ] add metrics;
 - [ ] add synchronization toolkit;
 - [ ] support and compatibility for AF_XDP socket;
 
+## 🏠 Architecture
+
+```mermaid
+graph TD
+    subgraph ApplicationFramework
+        Tower
+        Actix-Web
+        Rocket
+        warp
+        axum
+    end
+    subgraph MessageQueue
+        RocketMQ
+        Pulsar
+    end
+    subgraph RemoteProcedureCall
+        Dubbo
+        Tonic
+        gRPC-rs
+        Volo
+    end
+    subgraph Database
+        MySQL
+        Oracle
+    end
+    subgraph NetworkFramework
+        Tokio
+        monoio
+        async-std
+        smol
+    end
+    subgraph open-coroutine-architecture
+        subgraph core
+            Preemptive
+            ScalableStack
+            WorkSteal
+            Priority
+        end
+        subgraph hook
+            HookSyscall
+        end
+        subgraph macros
+            open-coroutine::main
+        end
+        subgraph open-coroutine
+        end
+        hook -->|depends on| core
+        open-coroutine -->|depends on| hook
+        open-coroutine -->|depends on| macros
+    end
+    subgraph OperationSystem
+        Linux
+        macOS
+        Windows
+    end
+    ApplicationFramework -->|maybe depends on| RemoteProcedureCall
+    ApplicationFramework -->|maybe depends on| MessageQueue
+    ApplicationFramework -->|maybe depends on| Database
+    MessageQueue -->|depends on| NetworkFramework
+    RemoteProcedureCall -->|depends on| NetworkFramework
+    NetworkFramework -->|runs on| OperationSystem
+    NetworkFramework -->|can depends on| open-coroutine-architecture
+    Database -->|runs on| OperationSystem
+    open-coroutine-architecture -->|runs on| OperationSystem
+```
+
 ## 📖 Quick Start
 
 ### step1: add dependency to your Cargo.toml
@@ -60,7 +128,9 @@ fn main() {
 }
 ```
 
-### create a task with priority(optional)
+## 🪽 Advanced Usage
+
+### create a task with priority
 
 ```rust
 #[open_coroutine::main]
@@ -71,7 +141,7 @@ fn main() {
 }
 ```
 
-### wait until the task is completed or timed out(optional)
+### wait until the task is completed or timed out
 
 ```rust
 #[open_coroutine::main]
@@ -83,7 +153,7 @@ fn main() {
 }
 ```
 
-### scalable stack(optional)
+### scalable stack
 
 ```rust
 #[open_coroutine::main]
@@ -112,3 +182,15 @@ fn main() {
 - [Monitor Overview](core/docs/en/monitor.md)
 
 [我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)
+
+## 🙏 Credits
+
+This crate was inspired by the following projects:
+
+- [acl](https://github.com/acl-dev/acl)
+- [coost](https://github.com/idealvin/coost)
+- [golang](https://github.com/golang/go)
+- [stacker](https://github.com/rust-lang/stacker)
+- [monoio](https://github.com/bytedance/monoio)
+- [compio](https://github.com/compio-rs/compio)
+- [may](https://github.com/Xudong-Huang/may)
diff --git a/README_ZH.md b/README_ZH.md
@@ -8,7 +8,7 @@
 [![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的平均时间")
 [![Percentage of issues still open](http://isitmaintained.com/badge/open/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine "仍未关闭issue的百分比")
 
-`open-coroutine`是一个简单、高效、通用的有栈协程库。
+`open-coroutine`是一个简单、高效、通用的有栈协程库，您可以将其用作IO线程池的性能替代。
 
 [English](README.md) | 中文
 
@@ -25,11 +25,79 @@
 
 ## 🕊 未来计划
 
+- [ ] 完善文档;
+- [ ] 增加性能[基准测试](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);
 - [ ] 取消协程/任务;
 - [ ] 增加性能指标;
 - [ ] 增加并发工具包;
 - [ ] 支持AF_XDP套接字;
 
+## 🏠 架构设计
+
+```mermaid
+graph TD
+    subgraph ApplicationFramework
+        Tower
+        Actix-Web
+        Rocket
+        warp
+        axum
+    end
+    subgraph MessageQueue
+        RocketMQ
+        Pulsar
+    end
+    subgraph RemoteProcedureCall
+        Dubbo
+        Tonic
+        gRPC-rs
+        Volo
+    end
+    subgraph Database
+        MySQL
+        Oracle
+    end
+    subgraph NetworkFramework
+        Tokio
+        monoio
+        async-std
+        smol
+    end
+    subgraph open-coroutine-architecture
+        subgraph core
+            Preemptive
+            ScalableStack
+            WorkSteal
+            Priority
+        end
+        subgraph hook
+            HookSyscall
+        end
+        subgraph macros
+            open-coroutine::main
+        end
+        subgraph open-coroutine
+        end
+        hook -->|depends on| core
+        open-coroutine -->|depends on| hook
+        open-coroutine -->|depends on| macros
+    end
+    subgraph OperationSystem
+        Linux
+        macOS
+        Windows
+    end
+    ApplicationFramework -->|maybe depends on| RemoteProcedureCall
+    ApplicationFramework -->|maybe depends on| MessageQueue
+    ApplicationFramework -->|maybe depends on| Database
+    MessageQueue -->|depends on| NetworkFramework
+    RemoteProcedureCall -->|depends on| NetworkFramework
+    NetworkFramework -->|runs on| OperationSystem
+    NetworkFramework -->|can depends on| open-coroutine-architecture
+    Database -->|runs on| OperationSystem
+    open-coroutine-architecture -->|runs on| OperationSystem
+```
+
 ## 📖 快速接入
 
 ### step1: 在你的Cargo.toml中添加依赖
@@ -60,7 +128,9 @@ fn main() {
 }
 ```
 
-### 创建具有优先级的任务(可选)
+## 🪽 进阶使用
+
+### 创建具有优先级的任务
 
 ```rust
 #[open_coroutine::main]
@@ -71,7 +141,7 @@ fn main() {
 }
 ```
 
-### 等待任务完成或超时(可选)
+### 等待任务完成或超时
 
 ```rust
 #[open_coroutine::main]
@@ -83,7 +153,7 @@ fn main() {
 }
 ```
 
-### 扩容栈(可选)
+### 扩容栈
 
 ```rust
 #[open_coroutine::main]
@@ -112,3 +182,15 @@ fn main() {
 - [语言选择](docs/cn/why-rust.md)
 
 [我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)
+
+## 🙏 鸣谢
+
+这个crate的灵感来自以下项目：
+
+- [acl](https://github.com/acl-dev/acl)
+- [coost](https://github.com/idealvin/coost)
+- [golang](https://github.com/golang/go)
+- [stacker](https://github.com/rust-lang/stacker)
+- [monoio](https://github.com/bytedance/monoio)
+- [compio](https://github.com/compio-rs/compio)
+- [may](https://github.com/Xudong-Huang/may)
diff --git a/core/docs/en/coroutine.md b/core/docs/en/coroutine.md
@@ -49,19 +49,19 @@ The above is excerpted from [corosensei](https://github.com/Amanieu/corosensei).
 
 ## Coroutine VS Thread
 
-|                   | coroutine | thread  |
-|-------------------|-----------|---------|
-| switch efficiency | ✅ Higher | ❌ High |
-| memory efficiency | KB/MB     | KB/MB   |
-| scheduled by OS   | ❌        | ✅      |
-| stack grow        | ✅        | ❌      |
+|                   | coroutine      | thread   |
+|-------------------|----------------|----------|
+| switch efficiency | ✅ Higher      | ❌ High  |
+| memory usage      | ✅ Bytes/KB/MB | ❌ KB/MB |
+| scheduled by OS   | ❌             | ✅       |
+| stack grow        | ✅             | ❌       |
 
 ## Stackfull VS Stackless
 
 |                   | stackfull | stackless |
 |-------------------|-----------|-----------|
 | switch efficiency | ❌ High   | ✅ Higher |
-| memory efficiency | ❌ KB/MB  | ✅ Bytes  |
+| memory usage      | ❌ KB/MB  | ✅ Bytes  |
 | limitations       | ✅ Few    | ❌ Many   |
 
 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.
 introduce `CoroutineLocal`. It's similar to `ThreadLocal`'s approach of providing replicas, but `CoroutineLocal` has
 upgraded the replicas to the coroutine level, which means each coroutine has its own local variables. These local
 variables will be dropped together when the coroutine is dropped.
+
+## [Scalable Stack Overview](scalable-stack.md)
diff --git a/core/docs/en/monitor.md b/core/docs/en/monitor.md
@@ -33,6 +33,7 @@ fn main() -> std::io::Result<()> {
     // is not enabled, it 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
     assert_eq!(CoroutineState::Suspend((), 0), coroutine.state());
     Ok(())
 }
@@ -43,7 +44,7 @@ fn main() -> std::io::Result<()> {
 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.
 
-## Why preempt
+## 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

diff --git a/core/docs/en/overview.md b/core/docs/en/overview.md
@@ -0,0 +1,20 @@
+## open-coroutine overview
+
+[![crates.io](https://img.shields.io/crates/v/open-coroutine.svg)](https://crates.io/crates/open-coroutine)
+[![docs.rs](https://img.shields.io/badge/docs-release-blue)](https://docs.rs/open-coroutine)
+[![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)
+[![Build Status](https://github.com/acl-dev/open-coroutine/workflows/CI/badge.svg)](https://github.com/acl-dev/open-coroutine/actions)
+[![Codecov](https://codecov.io/github/acl-dev/open-coroutine/graph/badge.svg?token=MSM3R7CBEX)](https://codecov.io/github/acl-dev/open-coroutine)
+[![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")
+[![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")
+
+The `open-coroutine` is a simple, efficient and generic stackfull-coroutine library, you can use this as a performance replacement for IO thread pools.
+
+[//]: # (todo 增加英文版本的文档)
+- [Background](../../../docs/cn/background.md)
+- [Why rust](../../../docs/cn/why-rust.md)
+- [Why better]()
+- [Quick Start](../../../README.md)
+- [Coroutine Overview](../en/coroutine.md)
+- [Scalable Stack Overview](../en/scalable-stack.md)
+- [Monitor Overview](../en/monitor.md)