Skip to content

Commit f7dc882

Browse files
contruncontrun
committed
rust async: add compilation flow, fix typos
1 parent 2ec00b8 commit f7dc882

File tree

2 files changed

+125
-39
lines changed

2 files changed

+125
-39
lines changed

‎org/20220118160327-lowering_async_await_in_rust.org

+50-39
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
:ID: 2e4ec310-908d-4aee-800e-af631f0967a5
33
:END:
44
#+title: lowering async await in rust
5+
#+filetags: :coroutine:llvm:code_generation:async_programming:rust:
56

67

78
We have a simple program ([[https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=91241061cec74bd633c22789f1ae1196][playground link]]) built with rust's async/await feature.
@@ -24,6 +25,12 @@ Here are a few references:
2425
+ [[https://github.com/rust-lang/rust/pull/43076/files][Generator support]]
2526
+ [[https://rust-lang.github.io/async-book/][Asynchronous Programming in Rust]]
2627

28+
Below is roughly how rust compiler compiles the rust source code into machine code.
29+
30+
[[file:assets/images/rust-compilation-flow.svg]]
31+
32+
We will dive into the code generation process of async/await in a moment.
33+
2734
* High level intermediate representations
2835

2936
Let's first try to expand all the macros with [[https://github.com/dtolnay/cargo-expand][cargo-expand]].
@@ -61,9 +68,9 @@ fn main() {
6168
}
6269
#+end_src
6370

64-
We can see that the async main function is replaced with a variable called body,
65-
and we now have a synchronous main function which stops at a [[https://docs.rs/tokio/latest/tokio/runtime/struct.Runtime.html#method.block_on][block_on]] function.
66-
The signature of block_on shows that it accepts a ~future~.
71+
We can see that the async main function is replaced with a variable called body.
72+
We now have a synchronous main function which stops at a [[https://docs.rs/tokio/latest/tokio/runtime/struct.Runtime.html#method.block_on][block_on]] function,
73+
whose signature shows that it accepts a [[https://doc.rust-lang.org/std/future/trait.Future.html][~future~]].
6774

6875
How does this ~async {sleep(Duration::from_secs(1)).await;}~ turn out to be a future?
6976

@@ -104,7 +111,7 @@ fn main() {
104111
}
105112
#+end_src
106113

107-
There are quite a few [[https://doc.rust-lang.org/beta/unstable-book/language-features/lang-items.html][lang_items]] in the snippet.
114+
There are quite a few [[https://doc.rust-lang.org/beta/unstable-book/language-features/lang-items.html][lang_items]] in this snippet.
108115
# [[https://manishearth.github.io/blog/2017/01/11/rust-tidbits-what-is-a-lang-item/][Rust Tidbits: What Is a Lang Item? - In Pursuit of Laziness]]
109116
We view those ~lang_items~ as compiler plugins to generate some specific codes (maybe from some specific inputs).
110117
For example, the ~lang_item~ ~from_generator~ is used to generate a future from a generator.
@@ -113,21 +120,21 @@ We used a few ~lang_items~ in our example. Here is [[https://github.com/rust-lan
113120
In our case, lowering to HIR is basically a combination of expanding async in ~async fn main { body }~ and
114121
expanding await in ~future.await~, where the body is our async main function, and future is our sleeping task.
115122

116-
These two expansion are accomplished by [[https://github.com/rust-lang/rust/blob/3ee016ae4d4c6ee4a34faa2eb7fdae2ffa7c9b46/compiler/rustc_ast_lowering/src/expr.rs#L518-L607][~make_async_expr~]] and [[https://github.com/rust-lang/rust/blob/3ee016ae4d4c6ee4a34faa2eb7fdae2ffa7c9b46/compiler/rustc_ast_lowering/src/expr.rs#L609-L800][~lower_expr_await]]~.
123+
These two expansion are accomplished by [[https://github.com/rust-lang/rust/blob/3ee016ae4d4c6ee4a34faa2eb7fdae2ffa7c9b46/compiler/rustc_ast_lowering/src/expr.rs#L518-L607][~make_async_expr~]] and [[https://github.com/rust-lang/rust/blob/3ee016ae4d4c6ee4a34faa2eb7fdae2ffa7c9b46/compiler/rustc_ast_lowering/src/expr.rs#L609-L800][~lower_expr_await~]].
117124

118125
~make_async_expr~ takes an async function or an async block, and converts it to a future.
119126
Below is its comment.
120127

121-
#+begin_src rust
122-
/// Lower an `async` construct to a generator that is then wrapped so it implements `Future`.
123-
///
124-
/// This results in:
125-
///
126-
/// ```text
127-
/// std::future::from_generator(static move? |_task_context| -> <ret_ty> {
128-
/// <body>
129-
/// })
130-
/// ```
128+
#+begin_src
129+
Lower an `async` construct to a generator that is then wrapped so it implements `Future`.
130+
131+
This results in:
132+
133+
```text
134+
std::future::from_generator(static move? |_task_context| -> <ret_ty> {
135+
<body>
136+
})
137+
```
131138
#+end_src
132139

133140

@@ -136,21 +143,21 @@ Below is its comment.
136143
Below is its comment.
137144

138145
#+begin_src rust
139-
/// Desugar `<expr>.await` into:
140-
/// ```rust
141-
/// match ::std::future::IntoFuture::into_future(<expr>) {
142-
/// mut pinned => loop {
143-
/// match unsafe { ::std::future::Future::poll(
144-
/// <::std::pin::Pin>::new_unchecked(&mut pinned),
145-
/// ::std::future::get_context(task_context),
146-
/// ) } {
147-
/// ::std::task::Poll::Ready(result) => break result,
148-
/// ::std::task::Poll::Pending => {}
149-
/// }
150-
/// task_context = yield ();
151-
/// }
152-
/// }
153-
/// ```
146+
Desugar `<expr>.await` into:
147+
```rust
148+
match ::std::future::IntoFuture::into_future(<expr>) {
149+
mut pinned => loop {
150+
match unsafe { ::std::future::Future::poll(
151+
<::std::pin::Pin>::new_unchecked(&mut pinned),
152+
::std::future::get_context(task_context),
153+
) } {
154+
::std::task::Poll::Ready(result) => break result,
155+
::std::task::Poll::Pending => {}
156+
}
157+
task_context = yield ();
158+
}
159+
}
160+
```
154161
#+end_src
155162

156163
Substitute all the variable values, ~body~ is then set to
@@ -176,18 +183,19 @@ We will come to the ~task_context~ thing in a later point.
176183
For now, we are satisfied with the fact that, ~task_context~ is passed from the async runtime and it is
177184
used by the reactor to notify the executor a future is ready to continue.
178185

179-
A bigger mystery is the ~yield~.
186+
The argument of ~from_generator~ seems to be a closure, but it is a generator.
187+
The secret lies in the ~yield~ statement.
180188

181189
* Generator code generation
182190

183191
What is this ~yield~ thing? We have encountered ~yield~ in other languages.
184192
Legend has it that in programming languages with cooperative multitasking feature,
185-
when one procedure runs to the yielding point it automagically gives up its control of the CPU, so that other tasks can continue.
186-
And when other procedures yield, it have a chance to continue. But how?
193+
when one procedure runs to the yielding point it automagically gives up its control of the CPU so that other tasks can continue,
194+
and when other procedures yield, it have a chance to continue. But how?
187195
Frequently it is implemented with [[https://en.wikipedia.org/wiki/Setjmp.h][~setjmp/longjmp~]]. What about rust? Is it using mechanism like that?
188196

189197
Let's go lower to [[https://rustc-dev-guide.rust-lang.org/mir/index.html][Rust's Mid-level Intermediate Representation (MIR)]] with ~RUSTFLAGS="--emit mir" cargo -v run~.
190-
Below is a sample MIR file (found in the path ~target/debug/deps/*.mir~).
198+
Below is MIR of the generated coroutine of the async main function (found in the path ~target/debug/deps/*.mir~).
191199

192200
#+begin_src rust-mir
193201
fn main::{closure#0}(_1: Pin<&mut [static generator@src/main.rs:4:17: 6:2]>, _2: ResumeTy) -> GeneratorState<(), ()> {
@@ -369,7 +377,8 @@ Our program decides jumping to which basic block based on the state's current di
369377
For example, when the discriminant is 0, the program jumps to ~bb1~.
370378
Some branch is unreachable because those discriminants are just not possible to have those values (the otherwise branch above).
371379
Some states (the 1_u32 and 2_u32 branches above) are malformed.
372-
The state 0_u32 means that we just started polling. When the sleeping task is finished, the state is transitioned to 3_u32.
380+
The state 0_u32 means that we just get started. The state 3_u32 means that polling is already started, but the task is not finished yet.
381+
When the sleeping task is finished, the state is transitioned to 1_u32.
373382

374383
Let's look at an exemplary state transition.
375384

@@ -419,12 +428,12 @@ Let's look at an exemplary state transition.
419428
~bb6~ and ~bb7~ obtains the result of the ~poll~ function of the sleeping future. Depending on whether the sleeping task is finished,
420429
the control flow may go from ~bb8~ to ~bb9~ (which sets the state to be 3) or ~bb11~ and ~bb12~ (which sets the state to be 1).
421430

422-
In summary, the rust compiler generates a closure which keeps the state of the coroutine.
423-
The state transition is driven by repeated execution of the closure.
431+
In summary, the rust compiler generates a closure which captures the state of the async block.
432+
The state transition is driven by repeated execution of this closure.
424433
The pausing of a coroutine is just an early return on no final results,
425434
while the resumption is just a rerun of the closure.
426435

427-
To make this more clearly, let's add one more suspension point ([[https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=573f94052c3485e3dba8f2d49cd1e7fa][playground link]]).
436+
To make this more clear, let's add one more suspension point ([[https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=573f94052c3485e3dba8f2d49cd1e7fa][playground link]]).
428437

429438
#+begin_src rust
430439
use tokio::time::{sleep, Duration};
@@ -436,7 +445,7 @@ async fn main() {
436445
}
437446
#+end_src
438447

439-
This time the entry point has one more branches to go. The new state 4_u32, which represents the time gap
448+
This time the entry point has one more branches to go. A new state 4_u32, which represents the time gap
440449
between the first future finished and the second future still running, is created.
441450

442451
#+begin_src rust-mir
@@ -532,3 +541,5 @@ So in our case, when the async runtime calls ~gen.resume(ResumeTy(NonNull::from(
532541
which is nothing but a wrapper of ~cx~, a [[https://docs.rs/futures/latest/futures/task/struct.Context.html][futures::task::Context]].
533542
In this way, futures inside the generator can inform the executor when they are ready to make progress
534543
(see [[https://rust-lang.github.io/async-book/02_execution/02_future.html][The Future Trait - Asynchronous Programming in Rust]] for more information).
544+
545+
# TODO: add generated code to illustrate how generator arguments are passed.

‎org/assets/images/rust-compilation-flow.svg

+75
Loading

0 commit comments

Comments
 (0)