add docs (#356)

Author: loongs-zhang

CHANGELOG.md

@@ -79,4 +79,4 @@
 - [x] higher level coroutine abstraction supported
 - [x] preemptive scheduling supported
 - [x] work stealing supported
-- [x] sleep system call hooks supported
+- [x] sleep syscall hooks supported

README.md

@@ -15,17 +15,18 @@ English | [中文](README_ZH.md)
 ## 🚀 Features
 
 - [x] Preemptive(`not supported in windows`): even if the coroutine enters a dead loop, it can still be seized, see [example](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/preemptive.rs);
-- [x] Hook: you are free to use most of the slow system calls in coroutine;
+- [x] Hook: you are free to use most of the slow syscall in coroutine, see supported syscall on [unix](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/unix.rs)/[windows](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/windows.rs);
 - [x] Scalable: the size of the coroutine stack supports unlimited expansion without the cost of copying stack, and immediately shrinks to the original size after use, see [example](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/scalable_stack.rs);
 - [x] io_uring(`only in linux`): supports and is compatible with io_uring in terms of local file IO and network IO. If it's not supported on your system, it will fall back to non-blocking IO;
-- [x] Priority: support custom task and coroutine priority;
-- [x] Work Stealing: internally using a lock free work steal queue;
-- [x] Compatibility: the implementation of open-coroutine is no async, but it is compatible with async, which means you can use this crate in tokio/async-std/smol/...;
+- [x] Priority: support custom task priority, note that coroutine priority is not open to users;
+- [x] Work Steal: internally using a lock free work steal queue;
+- [x] Compatibility: the implementation of open-coroutine is no async, but it is compatible with async, which means you can use this crate in `tokio/async-std/smol/...`;
 - [x] Platforms: running on Linux, macOS and Windows;
 
 ## 🕊 Roadmap
 
-- [ ] support `#[open_coroutine::all_join]` and `#[open_coroutine::any_join]` macro to wait coroutines;
+- [ ] cancel coroutine/task;
+- [ ] add metrics;
 - [ ] add synchronization toolkit;
 - [ ] support and compatibility for AF_XDP socket;
 
@@ -39,7 +40,7 @@ English | [中文](README_ZH.md)
 open-coroutine = "x.y.z"
 ```
 
-### step2: add macro
+### step2: add `open_coroutine::main` macro
 
 ```rust
 #[open_coroutine::main]
@@ -50,17 +51,39 @@ fn main() {
 
 ### step3: create a task
 
+```rust
+#[open_coroutine::main]
+fn main() {
+    _ = open_coroutine::task!(|param| {
+        assert_eq!(param, "param");
+    }, "param");
+}
+```
+
+### create a task with priority(optional)
+
+```rust
+#[open_coroutine::main]
+fn main() {
+    _ = open_coroutine::task!(|param| {
+        assert_eq!(param, "param");
+    }, "param", 1/*the smaller the value, the higher the priority*/);
+}
+```
+
+### wait until the task is completed or timed out(optional)
+
 ```rust
 #[open_coroutine::main]
 fn main() {
     let task = open_coroutine::task!(|param| {
-        assert_eq!(param, 1);
-    }, 1);
+        assert_eq!(param, "param");
+    }, "param", 1);
     task.timeout_join(std::time::Duration::from_secs(1)).expect("timeout");
 }
 ```
 
-### step4: scalable stack(optional)
+### scalable stack(optional)
 
 ```rust
 #[open_coroutine::main]
@@ -83,6 +106,6 @@ fn main() {
 }
 ```
 
-## ⚓ Learn
+## ⚓ Learn More
 
 [我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)

README_ZH.md

@@ -5,8 +5,8 @@
 [![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")
+[![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`是一个简单、高效、通用的有栈协程库。
 
@@ -15,17 +15,18 @@
 ## 🚀 当前特性
 
 - [x] 抢占调度(`不支持windows`): 即使协程进入死循环，它仍能被抢占，查看[例子](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/preemptive.rs);
-- [x] Hook: 您可以在协程中自由使用大多数慢系统调用;
+- [x] Hook: 您可以在协程中自由使用大多数慢系统调用，查看支持的系统调用[unix](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/unix.rs)/[windows](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/windows.rs);
 - [x] 可伸缩栈: 协程栈的大小支持无限制扩容而没有复制堆栈的开销，查看[例子](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/scalable_stack.rs);
 - [x] io_uring(`只支持linux`): 在本地文件IO和网络IO方面支持并兼容io_uring。如果您的系统不支持，它将回退到NIO;
-- [x] 优先级: 支持自定义任务和协程的优先级;
+- [x] 优先级: 支持自定义任务优先级，注意协程优先级未对用户开放;
 - [x] 任务窃取: 内部使用无锁任务窃取队列;
-- [x] 兼容性: open-coroutine的实现是No async的，但它与async兼容，这意味着您可以在tokio/sync-std/smol/...中使用这个crate;
+- [x] 兼容性: open-coroutine的实现是No async的，但它与async兼容，这意味着您可以在`tokio/sync-std/smol/...`中使用这个crate;
 - [x] 跨平台: 支持Linux、macOS和Windows;
 
 ## 🕊 未来计划
 
-- [ ] 支持`#[open_coroutine::all_join]`和`#[open_coroutine::any_join]`宏;
+- [ ] 取消协程/任务;
+- [ ] 增加性能指标;
 - [ ] 增加并发工具包;
 - [ ] 支持AF_XDP套接字;
 
@@ -39,7 +40,7 @@
 open-coroutine = "x.y.z"
 ```
 
-### step2: 添加宏
+### step2: 添加`open_coroutine::main`宏
 
 ```rust
 #[open_coroutine::main]
@@ -50,17 +51,39 @@ fn main() {
 
 ### step3: 创建任务
 
+```rust
+#[open_coroutine::main]
+fn main() {
+    _ = open_coroutine::task!(|param| {
+        assert_eq!(param, "param");
+    }, "param");
+}
+```
+
+### 创建具有优先级的任务(可选)
+
+```rust
+#[open_coroutine::main]
+fn main() {
+    _ = open_coroutine::task!(|param| {
+        assert_eq!(param, "param");
+    }, "param", 1/*数值越小，优先级越高*/);
+}
+```
+
+### 等待任务完成或超时(可选)
+
 ```rust
 #[open_coroutine::main]
 fn main() {
     let task = open_coroutine::task!(|param| {
-        assert_eq!(param, 1);
-    }, 1);
+        assert_eq!(param, "param");
+    }, "param", 1);
     task.timeout_join(std::time::Duration::from_secs(1)).expect("timeout");
 }
 ```
 
-### step4: 扩容栈(可选)
+### 扩容栈(可选)
 
 ```rust
 #[open_coroutine::main]
@@ -83,6 +106,9 @@ fn main() {
 }
 ```
 
-## ⚓ 学习更多
+## ⚓ 了解更多
+
+- [诞生之因](docs/cn/background.md)
+- [语言选择](docs/cn/why-rust.md)
 
 [我有故事,你有酒吗?](https://github.com/acl-dev/open-coroutine-docs)

core/src/co_pool/creator.rs

@@ -17,7 +17,7 @@ impl Listener<(), Option<usize>> for CoroutineCreator {
         new_state: SchedulableCoroutineState,
     ) {
         match new_state {
-            CoroutineState::Suspend((), _) | CoroutineState::SystemCall((), _, _) => {
+            CoroutineState::Suspend((), _) | CoroutineState::Syscall((), _, _) => {
                 if let Some(pool) = CoroutinePool::current() {
                     _ = pool.try_grow();
                 }

core/src/common/constants.rs

@@ -46,7 +46,7 @@ impl_display_by_debug!(PoolState);
 #[allow(non_camel_case_types, missing_docs)]
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
-pub enum Syscall {
+pub enum SyscallName {
     #[cfg(windows)]
     Sleep,
     sleep,
@@ -131,7 +131,7 @@ pub enum Syscall {
     WSAPoll,
 }
 
-impl Syscall {
+impl SyscallName {
     /// Get the `NIO` syscall.
     #[must_use]
     pub fn nio() -> Self {
@@ -158,10 +158,10 @@ impl Syscall {
     }
 }
 
-impl_display_by_debug!(Syscall);
+impl_display_by_debug!(SyscallName);
 
-impl From<Syscall> for &str {
-    fn from(val: Syscall) -> Self {
+impl From<SyscallName> for &str {
+    fn from(val: SyscallName) -> Self {
         format!("{val}").leak()
     }
 }
@@ -193,8 +193,8 @@ pub enum CoroutineState<Y, R> {
     Running,
     ///The coroutine resumes execution after the specified time has been suspended(with a given value).
     Suspend(Y, u64),
-    ///The coroutine enters the system call.
-    SystemCall(Y, Syscall, SyscallState),
+    ///The coroutine enters the syscall.
+    Syscall(Y, SyscallName, SyscallState),
     /// The coroutine completed with a return value.
     Complete(R),
     /// The coroutine completed with a error message.

core/src/config.rs

@@ -16,7 +16,7 @@ pub struct Config {
 impl Config {
     #[must_use]
     pub fn single() -> Self {
-        Self::new(1, DEFAULT_STACK_SIZE, 0, 65536, 0, 0, 10_000_000_000, true)
+        Self::new(1, DEFAULT_STACK_SIZE, 0, 65536, 0, 0, 0, true)
     }
 
     #[allow(clippy::too_many_arguments)]
@@ -136,15 +136,6 @@ impl Config {
 
 impl Default for Config {
     fn default() -> Self {
-        Self::new(
-            cpu_count(),
-            DEFAULT_STACK_SIZE,
-            0,
-            65536,
-            0,
-            0,
-            10_000_000_000,
-            true,
-        )
+        Self::new(cpu_count(), DEFAULT_STACK_SIZE, 0, 65536, 0, 0, 0, true)
     }
 }

core/src/coroutine/korosensei.rs

@@ -447,8 +447,8 @@ where
                         self.suspend(y, timestamp)?;
                         Ok(CoroutineState::Suspend(y, timestamp))
                     }
-                    CoroutineState::SystemCall(y, syscall, state) => {
-                        Ok(CoroutineState::SystemCall(y, syscall, state))
+                    CoroutineState::Syscall(y, syscall, state) => {
+                        Ok(CoroutineState::Syscall(y, syscall, state))
                     }
                     _ => Err(Error::new(
                         ErrorKind::Other,

core/src/coroutine/stack_pool.rs

@@ -159,7 +159,7 @@ unsafe impl Sync for MemoryPool {}
 
 impl Default for MemoryPool {
     fn default() -> Self {
-        Self::new(0, 10_000_000_000)
+        Self::new(0, 0)
     }
 }
 

core/src/coroutine/state.rs

@@ -1,4 +1,4 @@
-use crate::common::constants::{CoroutineState, Syscall, SyscallState};
+use crate::common::constants::{CoroutineState, SyscallName, SyscallState};
 use crate::common::now;
 use crate::coroutine::listener::Listener;
 use crate::coroutine::Coroutine;
@@ -67,7 +67,7 @@ where
         let current = self.state();
         match current {
             CoroutineState::Running => return Ok(()),
-            CoroutineState::Ready | CoroutineState::SystemCall(_, _, SyscallState::Executing) => {
+            CoroutineState::Ready | CoroutineState::Syscall(_, _, SyscallState::Executing) => {
                 let new_state = CoroutineState::Running;
                 let old_state = self.change_state(new_state);
                 self.on_running(self, old_state);
@@ -82,7 +82,7 @@ where
                     return Ok(());
                 }
             }
-            CoroutineState::SystemCall(_, _, SyscallState::Callback | SyscallState::Timeout) => {
+            CoroutineState::Syscall(_, _, SyscallState::Callback | SyscallState::Timeout) => {
                 return Ok(());
             }
             _ => {}
@@ -127,20 +127,20 @@ where
     pub fn syscall(
         &self,
         val: Yield,
-        syscall: Syscall,
+        syscall: SyscallName,
         syscall_state: SyscallState,
     ) -> std::io::Result<()> {
         let current = self.state();
         match current {
             CoroutineState::Running => {
-                let new_state = CoroutineState::SystemCall(val, syscall, syscall_state);
+                let new_state = CoroutineState::Syscall(val, syscall, syscall_state);
                 let old_state = self.change_state(new_state);
                 self.on_syscall(self, old_state);
                 return Ok(());
             }
-            CoroutineState::SystemCall(_, original_syscall, _) => {
+            CoroutineState::Syscall(_, original_syscall, _) => {
                 if original_syscall == syscall {
-                    let new_state = CoroutineState::SystemCall(val, syscall, syscall_state);
+                    let new_state = CoroutineState::Syscall(val, syscall, syscall_state);
                     let old_state = self.change_state(new_state);
                     self.on_syscall(self, old_state);
                     return Ok(());
@@ -153,7 +153,7 @@ where
             format!(
                 "{} unexpected {current}->{:?}",
                 self.name(),
-                CoroutineState::<Yield, Return>::SystemCall(val, syscall, syscall_state)
+                CoroutineState::<Yield, Return>::Syscall(val, syscall, syscall_state)
             ),
         ))
     }
@@ -250,13 +250,13 @@ mod tests {
         let co = co!(|_: &Suspender<(), ()>, ()| {})?;
         assert_eq!(CoroutineState::Ready, co.state());
         co.running()?;
-        co.syscall((), Syscall::nanosleep, SyscallState::Executing)?;
+        co.syscall((), SyscallName::nanosleep, SyscallState::Executing)?;
         assert_eq!(
-            CoroutineState::SystemCall((), Syscall::nanosleep, SyscallState::Executing),
+            CoroutineState::Syscall((), SyscallName::nanosleep, SyscallState::Executing),
             co.state()
         );
         assert!(co
-            .syscall((), Syscall::sleep, SyscallState::Executing)
+            .syscall((), SyscallName::sleep, SyscallState::Executing)
             .is_err());
         Ok(())
     }

core/src/lib.rs

@@ -60,7 +60,7 @@ pub mod common;
 #[allow(missing_docs)]
 pub mod config;
 
-/// Coroutine impls.
+#[doc = include_str!("../../docs/en/coroutine.md")]
 pub mod coroutine;
 
 /// Make the coroutine automatically yield.