From 593f8704036a0308dacd2a3d7ce9b7ddee822d66 Mon Sep 17 00:00:00 2001
From: Xu Shaohua <shaohua@biofan.org>
Date: Thu, 14 Mar 2024 17:46:15 +0800
Subject: [PATCH] async: Add async await

---
 src/SUMMARY.md                 |  5 +++--
 src/async/async-await.md       | 11 ++++++++++-
 src/async/debug.md             |  6 ++++++
 src/async/futures-and-tasks.md |  5 ++++-
 src/async/index.md             |  2 ++
 src/async/lifetimes-pinning.md |  1 +
 src/async/mem-pinning.md       |  1 -
 7 files changed, 26 insertions(+), 5 deletions(-)
 create mode 100644 src/async/debug.md
 create mode 100644 src/async/lifetimes-pinning.md
 delete mode 100644 src/async/mem-pinning.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index e5f9bdb..06d9885 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -166,16 +166,17 @@
 - [异步 async](async/index.md)
     - [理解 Futures 与 Tasks](async/futures-and-tasks.md)
     - [理解 async/await](async/async-await.md)
-    - [内存保持 Pinning](async/mem-pinning.md)
+    - [生命周期与内存保持 Lifetimes and Pinning](async/lifetimes-pinning.md)
     - [流 Streams](async/streams.md)
     - [一次执行多个 Futures](async/multi-futures.md)
     - [标准库中的 future 模块](async/future-module.md)
-    - [mio 库](async/mio.md)
     - [futures 库](async/futures-crate.md)
+    - [mio 库](async/mio.md)
     - [运行时](async/runtime.md)
         - [tokio 库](async/runtime/tokio.md)
         - [async-std 库](async/runtime/async-std.md)
         - [smol 库](async/runtime/smol.md)
+    - [如何调试 debug](async/debug.md)
 - [宏](macro/index.md)
     - [宏 Macro](macro/macro.md)
     - [宏示例](macro/macro-example.md)
diff --git a/src/async/async-await.md b/src/async/async-await.md
index ee54dc0..10e6dc4 100644
--- a/src/async/async-await.md
+++ b/src/async/async-await.md
@@ -1 +1,10 @@
-# 理解 async/await
\ No newline at end of file
+# 理解 async/await
+
+rustc 编译器遇到 async 函数时, 会在内部生成对应的状态机代码 (state machine), 这个状态机会实现
+`Future` trait.
+
+## 参考
+
+- [Understanding Async Await in Rust: From State Machines to Assembly Code](https://eventhelix.com/rust/rust-to-assembly-async-await/)
+- [Nested async/await in Rust: Desugaring and assembly](https://eventhelix.com/rust/rust-to-assembly-async-await-nested/)
+- [Rust async/await: Async executor](https://eventhelix.com/rust/rust-async-executor/)
diff --git a/src/async/debug.md b/src/async/debug.md
new file mode 100644
index 0000000..43f2469
--- /dev/null
+++ b/src/async/debug.md
@@ -0,0 +1,6 @@
+# 如何调试 debug
+
+## 参考
+
+- [tokie-console](https://github.com/tokio-rs/console)
+- [Writing a basic `async` debugger](https://cliffle.com/blog/lildb/)
\ No newline at end of file
diff --git a/src/async/futures-and-tasks.md b/src/async/futures-and-tasks.md
index 758953a..348a73f 100644
--- a/src/async/futures-and-tasks.md
+++ b/src/async/futures-and-tasks.md
@@ -1 +1,4 @@
-# 理解 Futures 与 Tasks
\ No newline at end of file
+# 理解 Futures 与 Tasks
+
+在同步式的代码 (synchronous code) 里调用阻塞函数(blocking function), 会阻塞整个线程;
+而在异步式的代码里, `Future` 会把控制权返还给线程, 这样其它的 `Future` 就可以运行了.
\ No newline at end of file
diff --git a/src/async/index.md b/src/async/index.md
index f6caa67..d4f47f0 100644
--- a/src/async/index.md
+++ b/src/async/index.md
@@ -26,3 +26,5 @@ Rust 实现的异步式(async)并发编程模型, 有这些特点:
 ## 参考
 
 - [Rust async book](https://rust-lang.github.io/async-book/)
+- [Async Rust Is A Bad Language](https://bitbashing.io/async-rust.html)
+- [Common Mistakes with Rust Async](https://www.qovery.com/blog/common-mistakes-with-rust-async/)
\ No newline at end of file
diff --git a/src/async/lifetimes-pinning.md b/src/async/lifetimes-pinning.md
new file mode 100644
index 0000000..1f5a2df
--- /dev/null
+++ b/src/async/lifetimes-pinning.md
@@ -0,0 +1 @@
+# 生命周期与内存保持 Lifetimes and Pinning
\ No newline at end of file
diff --git a/src/async/mem-pinning.md b/src/async/mem-pinning.md
deleted file mode 100644
index 25928cc..0000000
--- a/src/async/mem-pinning.md
+++ /dev/null
@@ -1 +0,0 @@
-# 内存保持 Pinning
\ No newline at end of file