Add an "async" session #496

djmitche · 2023-03-10T16:39:53Z

This is a continuation of #492, but against a branch in the upstream repo so that @rbehjati and I can both make PRs against it. Once the session is complete we can merge this PR to put it into main.

NOTE: `mdbook test` does not allow code samples to reference other crates, so they must be marked as `compile_fail`; see #175.

These concepts are closely related, and there's not much else to know about runtimes other than "they exist". This removes the bit about futures being "inert" because it doesn't really lead anywhere.

* Add async channels chapter * Async control flow * Async pitfalls * Separate in multiple chapters + add daemon section * Merge reentering threads in blocking-executor

rbehjati

Thanks for putting this together.

My general impression is that this is more like a chapter on tokio than async. Is that the intention? In particular, I think most of the basic concepts can be demonstrated using the futures crate, and with less boilerplate code.

Also, I remember there were some discussions about whether the content is for a full-day or a half-day session. Looks like we are aiming for the latter (i.e., day 4 afternoon after a morning on concurrency). This means we have only 2 hours for teaching this content. I feel like the content is too heavy for only 2 hours.

src/async/async-await.md

src/async/async-blocks.md

src/async/futures.md

rbehjati · 2023-04-04T06:29:06Z

src/SUMMARY.md

+  - [async/await](async/async-await.md)
+  - [Async Blocks](async/async-blocks.md)
+  - [Futures](async/futures.md)
+  - [Runtimes](async/runtimes.md)


I think it is better to talk about select & join earlier. I am guessing a question about that will come up rather early.

I'm not sure how or where.. they are simple to understand but a little more complicated to demonstrate.

src/async/pitfalls/blocking-executor.md

rbehjati · 2023-04-04T07:16:11Z

src/async/pitfalls/async-traits.md

+```
+
+<details>  
+


Perhaps add a note on why this is not supported (i.e., the resulting type not having a known type at compile time), and the overhead of using async_trait (because it does heap allocation).

By "supported", do you mean why this isn't stabilized?

I don't know enough about that to summarize - perhaps you can add something? I read a lot of blog posts on the topic!!

Sure. I can add something once you've merged #556. I think I learnt about it in an episode of Crust of Rust. We could also leave it out, as it might be too much detail.

I think the instructors can choose to go into more depth as they see fit when teaching the course. We don't need to cover everything in the notes, but since the speaker notes for this section are are already so comprehensive, I was tempted to suggest adding this too :)

#556 is merged. It can't hurt to include in the notes - maybe with an "If a student asks.." preface?

If think I know why but I would have a hard time explaining, so let me provide a pointer and you can explain better than me:

If you had a trait with fn fetch_data_count(&self) -> usize, then the compiler knows that it needs to push 64 bits to the stack for the return value, whatever the type of the caller.

Now if we had async fn fetch_data_count(&self) -> usize, since we actually return a future, the stack of the future needs to also be allocated, so the size of the return value depends on the actual method.

Consider both implementations:

async fn fetch_data_count(&self) -> usize { let data: [i32; 1000] = fetch().await; let filter: i32 = fetch_filter().await; data.iter().filter(|&item| item != filter).count() }

async fn fetch_data_count(&self) -> usize { let data: Vec<i32> = fetch().await; let filter: i32 = fetch_filter().await; data.iter().filter(|&item| item != filter).count() }

Example one, with the data on the stack probably has a higher size than the second one with the Vec. Using dynamic dispatch, it would be impossible for the compiler to know ahead of time the size.

Heap allocating fixes the size issue. Note that Box does not always allocate and the compiler is often able to omit allocations if it can figure out the size

Yes. Exactly. And I just noticed that I have a typo in my original comment; it should be "the resulting type not having a known size at compile time".

We cannot add all the details in the notes, so I was thinking of just a two sentence summary. I'll create a PR.

Sizing is a difficulty, but not the only one. Offhand, there's also:

Bounds on the future (most notably Send)

Bounds on the associated types (most notably lifetime)

Specifying associated type values to allow use as dyn Trait

(Formerly) each method (under the hood) needs an associated type, which must be generic and therefore needs GATs

Other design hairiness such as duplication vs parameterization (keyword generics, trait transformers, etc.)

It doesn't seem worth diving into all of these, but it feels misleading to suggest that Sized is the only one.

I think Niko Matsakis's 2019 post remains the best overview of the challenges. It's what I'd send to anyone wondering "why not...?". There's been a lot written since then about potential designs and the tradeoffs, but none of it seems "settled enough" to incorporate (at least to me, a person who follows progress from a distance).

djmitche · 2023-04-04T14:21:06Z

Thanks for taking a comprehensive look at the assembled afternoon! I've not gotten a chance to do so myself but I will do so shortly.

I agree that this is far too much content for 2 hours (and yes, that's been the intended timeframe). In that time I think we can only remove some of the mystery around async Rust. I suspect the situation is similar with Android + Rust -- students have the context to begin working with Rust in Android, but will still need to learn the details.

As for whether it's a tokio tutorial or not: the options for async things that will run in the playground are pretty limited, and in particular tokio appears to be the only available runtime. Is that what you're referring to, or are you concerned with the more particular bits about channels and async mutexes and so on?

rbehjati · 2023-04-04T16:45:13Z

As for whether it's a tokio tutorial or not: the options for async things that will run in the playground are pretty limited, and in particular tokio appears to be the only available runtime. Is that what you're referring to, or are you concerned with the more particular bits about channels and async mutexes and so on?

I was thinking mostly about the first few slides. I think it is too much to talk about tokio and runtimes in the first or second slides. I can try and rewrite src/async/async-await.md without using tokio, or at least without using time and spawn. I think in that first slide, we just want to talk about the basic syntax. I feel like there are currently too many new things in that slide.

djmitche · 2023-04-04T21:12:57Z

That's fair - let's see what you can come up with. I felt pretty constrained by having to write something that ran in the playground, but maybe I missed something, or maybe that constraint can be relaxed.

* Simplify the async-await slide * Shorten futures and move it up * Add a page on Tokio

djmitche

OK! I've made a PR addressing most of these comments: #556.

djmitche · 2023-04-05T21:39:09Z

src/async/control-flow/select.md

+
+* In this example, we have a race between a cat and a dog. `first_animal_to_finish_race` listens to both channels and will pick whichever arrives first. Since the dog takes 5 seconds, it wins against the cat that take 10 seconds.
+* You can use `oneshot` channels in this example as the channels are supposed to receive only one `send`.
+* You can try adding more contestants to the race and return a leaderboard. Also, you can add a deadline after which contestants get eliminated.


I think the deadline part of this "Try .." feels less contrived, so I'll stick with that.

djmitche · 2023-04-05T21:41:10Z

src/async/pitfalls/async-traits.md

+```
+
+<details>  
+


By "supported", do you mean why this isn't stabilized?

src/async/pitfalls/blocking-executor.md

djmitche · 2023-04-05T21:48:04Z

src/SUMMARY.md

+  - [async/await](async/async-await.md)
+  - [Async Blocks](async/async-blocks.md)
+  - [Futures](async/futures.md)
+  - [Runtimes](async/runtimes.md)


I'm not sure how or where.. they are simple to understand but a little more complicated to demonstrate.

* Modifications to the async section * Remove the "Daemon" slide, as it largely duplicates the "Tasks" slide. The introduction to the "Control Flow" section mentions tasks as a kind of control flow. * Reorganize the structure in SUMMARY.md to correspond to the directory structure. * Simplify the "Pin" and "Blocking the Executor" slides with steps in the speaker notes to demonstrate / fix the issues. * Rename "join_all" to "Join". * Simplify some code samples to shorten them, and to print output rather than asserting. * Clarify speaker notes and include more "Try.." suggestions. * Be consistent about where `async` blocks are introduced (in the "Tasks" slide). * Explain `join` and `select` in prose. * Fix formatting of section-header slides.

djmitche · 2023-04-07T23:17:11Z

I want to use some new stuff that's in main for the exercises, so I'll do that in a separate PR. This is ready for review.

rbehjati

Looks great. Thanks.

rbehjati · 2023-04-11T04:18:38Z

src/async/pitfalls/async-traits.md

+```
+
+<details>  
+


Yes. Exactly. And I just noticed that I have a typo in my original comment; it should be "the resulting type not having a known size at compile time".

We cannot add all the details in the notes, so I was thinking of just a two sentence summary. I'll create a PR.

mauvealerts · 2023-04-13T20:39:58Z

src/async/control-flow/select.md

+* Try adding a deadline to the race, demonstrating selecting different sorts of
+  futures.
+
+* Note that `select!` consumes the futures it is given, and is easiest to use


Nit: maybe add "by default"?

select! doesn't have to consume the future (in the fn(s: Foo) sense). It works with mutable references too. Maybe this isn't worth bothering with since the "pin" section demonstrates this; I just found the wording confusing/misleading on first read.

mauvealerts · 2023-04-14T08:26:22Z

src/async/pitfalls/async-traits.md

+```
+
+<details>  
+


Sizing is a difficulty, but not the only one. Offhand, there's also:

Bounds on the future (most notably Send)

Bounds on the associated types (most notably lifetime)

Specifying associated type values to allow use as dyn Trait

(Formerly) each method (under the hood) needs an associated type, which must be generic and therefore needs GATs

Other design hairiness such as duplication vs parameterization (keyword generics, trait transformers, etc.)

It doesn't seem worth diving into all of these, but it feels misleading to suggest that Sized is the only one.

I think Niko Matsakis's 2019 post remains the best overview of the challenges. It's what I'd send to anyone wondering "why not...?". There's been a lot written since then about potential designs and the tradeoffs, but none of it seems "settled enough" to incorporate (at least to me, a person who follows progress from a distance).

src/async/pitfalls/pin.md

mauvealerts · 2023-04-14T09:33:00Z

src/async/tasks.md

+
+        println!("connection from {addr:?}");
+
+        tokio::spawn(async move {


This is the first time async blocks appear (also alluded to in async-await and pin sections). They probably merit a sentence somewhere.

That's mentioned in the speaker notes. In general, it's a non-goal to put all explanation on the slide itself.

Ah, this was a failure in my search. I agree the note in speaker notes is good and sufficient.

For context, I noticed async move later and was trying to find where async blocks was explained/mentioned. Both "async" and "block" appear a lot, so I searched for async block, async {, or async move. (I don't think there's anything actionable here.)

mgeisler

Thanks @djmitche, @rbehjati, and @sakex for all your work on this!

I really like the notes, they helped me a lot in understanding the slides.

I've left a few small comments which can be fixed after merging the PR — I think it'll be great to get this published so that we can get some more real-world feedback on it.

src/SUMMARY.md

src/async/tasks.md

mgeisler · 2023-04-14T10:20:50Z

src/running-the-course/day-4.md

+
+If you chose Async for Day 4 afternoon, you will need a fresh crate set up and
+the dependencies downloaded and ready to go. You can then copy/paste the
+examples into `src/main.rs` to experiment with them.


I would suggest adding the large async examples to the repository as full Cargo projects (similar to how the Android chapter handles things).

That makes it trivial for an instructor to find known-good versions of the code, and we also get coverage from cargo build when you add those projects to the workspace for the repository.

src/exercises/day-4/async.md

djmitche · 2023-04-14T14:05:26Z

Thanks! I'll make up some new PRs and/or issues to address these items.

These address some comments in google#496.

These address some comments in #496.

* beginning of an Async section * address review comments * Add futures page (google#497) NOTE: `mdbook test` does not allow code samples to reference other crates, so they must be marked as `compile_fail`; see google#175. * Add Runtimes & Tasks (google#522) These concepts are closely related, and there's not much else to know about runtimes other than "they exist". This removes the bit about futures being "inert" because it doesn't really lead anywhere. * Async chapter (google#524) * Add async channels chapter * Async control flow * Async pitfalls * Separate in multiple chapters + add daemon section * Merge reentering threads in blocking-executor * async_trait * Async fixes (google#546) * Async: some ideas for simplifying the content (google#550) * Simplify the async-await slide * Shorten futures and move it up * Add a page on Tokio * Modifications to the async section (google#556) * Modifications to the async section * Remove the "Daemon" slide, as it largely duplicates the "Tasks" slide. The introduction to the "Control Flow" section mentions tasks as a kind of control flow. * Reorganize the structure in SUMMARY.md to correspond to the directory structure. * Simplify the "Pin" and "Blocking the Executor" slides with steps in the speaker notes to demonstrate / fix the issues. * Rename "join_all" to "Join". * Simplify some code samples to shorten them, and to print output rather than asserting. * Clarify speaker notes and include more "Try.." suggestions. * Be consistent about where `async` blocks are introduced (in the "Tasks" slide). * Explain `join` and `select` in prose. * Fix formatting of section-header slides. * Add a note on async trait (google#558) --------- Co-authored-by: sakex <[email protected]> Co-authored-by: rbehjati <[email protected]>

These address some comments in google#496.

djmitche and others added 6 commits March 10, 2023 14:07

beginning of an Async section

307ea61

address review comments

7515eb2

Add futures page (#497)

665e898

NOTE: `mdbook test` does not allow code samples to reference other crates, so they must be marked as `compile_fail`; see #175.

Add Runtimes & Tasks (#522)

1cff6e3

These concepts are closely related, and there's not much else to know about runtimes other than "they exist". This removes the bit about futures being "inert" because it doesn't really lead anywhere.

Async chapter (#524)

cd17c6b

* Add async channels chapter * Async control flow * Async pitfalls * Separate in multiple chapters + add daemon section * Merge reentering threads in blocking-executor

async_trait

281a8e6

sakex force-pushed the issue181 branch from f451979 to 281a8e6 Compare April 3, 2023 16:14

rbehjati reviewed Apr 4, 2023

View reviewed changes

Async fixes (#546)

8e121bc

Async: some ideas for simplifying the content (#550)

8dee189

* Simplify the async-await slide * Shorten futures and move it up * Add a page on Tokio

djmitche mentioned this pull request Apr 5, 2023

Modifications to the async section #556

Merged

djmitche commented Apr 5, 2023

View reviewed changes

djmitche marked this pull request as ready for review April 7, 2023 23:16

djmitche requested review from mgeisler, rbehjati and sakex April 7, 2023 23:17

djmitche mentioned this pull request Apr 8, 2023

Add a new async exercise: elevator simulation. #557

Merged

sakex approved these changes Apr 9, 2023

View reviewed changes

rbehjati approved these changes Apr 11, 2023

View reviewed changes

rbehjati mentioned this pull request Apr 11, 2023

Add a note on async trait #558

Merged

Add a note on async trait (#558)

27135e1

mauvealerts reviewed Apr 14, 2023

View reviewed changes

mgeisler approved these changes Apr 14, 2023

View reviewed changes

mgeisler reviewed Apr 14, 2023

View reviewed changes

src/exercises/day-4/async.md Show resolved Hide resolved

Merge branch 'main' into issue181

50928ce

djmitche enabled auto-merge (squash) April 14, 2023 14:04

djmitche merged commit 0d30da7 into main Apr 14, 2023

djmitche deleted the issue181 branch April 14, 2023 14:06

djmitche added a commit to djmitche/comprehensive-rust that referenced this pull request Apr 14, 2023

Minor fix-ups to the async section.

c5f1f70

These address some comments in google#496.

This was referenced Apr 14, 2023

Minor fix-ups to the async section. #566

Merged

Add async examples that can't run in playground as cargo crates #567

Open

djmitche added a commit that referenced this pull request Apr 16, 2023

Minor fix-ups to the async section. (#566)

d143528

These address some comments in #496.

NoahDragon pushed a commit to wnghl/comprehensive-rust that referenced this pull request Jul 19, 2023

Minor fix-ups to the async section. (google#566)

b5b1d6f

These address some comments in google#496.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add an "async" session #496

Add an "async" session #496

djmitche commented Mar 10, 2023

rbehjati left a comment

rbehjati Apr 4, 2023

djmitche Apr 5, 2023

rbehjati Apr 4, 2023

djmitche Apr 5, 2023

rbehjati Apr 6, 2023

djmitche Apr 6, 2023

rbehjati Apr 6, 2023

djmitche Apr 6, 2023

sakex Apr 9, 2023

sakex Apr 9, 2023 •

edited

Loading

rbehjati Apr 11, 2023

mauvealerts Apr 14, 2023

djmitche commented Apr 4, 2023

rbehjati commented Apr 4, 2023

djmitche commented Apr 4, 2023

djmitche left a comment

djmitche Apr 5, 2023

djmitche Apr 5, 2023

djmitche Apr 5, 2023

djmitche commented Apr 7, 2023

rbehjati left a comment

rbehjati Apr 11, 2023

mauvealerts Apr 13, 2023

mauvealerts Apr 14, 2023

mauvealerts Apr 14, 2023

djmitche Apr 14, 2023

mauvealerts Apr 14, 2023

mgeisler left a comment

mgeisler Apr 14, 2023

djmitche Apr 14, 2023

mgeisler Apr 17, 2023

djmitche commented Apr 14, 2023


		println!("connection from {addr:?}");

		tokio::spawn(async move {

		```

		<details>

		```

		<details>

		```

		<details>

		```

		<details>

Add an "async" session #496

Add an "async" session #496

Conversation

djmitche commented Mar 10, 2023

rbehjati left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sakex Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Apr 4, 2023

rbehjati commented Apr 4, 2023

djmitche commented Apr 4, 2023

djmitche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Apr 7, 2023

rbehjati left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgeisler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Apr 14, 2023

sakex Apr 9, 2023 •

edited

Loading