Stream: wg-async-foundations/book

Topic: reorganization


nikomatsakis (Jun 14 2019 at 16:57, on Zulip):

Hey, so I've been playing with a possible reorganization for the async book. You can get a feel for it here:

https://github.com/nikomatsakis/async-book/blob/master/src/SUMMARY.md

nikomatsakis (Jun 14 2019 at 16:57, on Zulip):

the high-level idea is to pull the async-await material up higher

nikomatsakis (Jun 14 2019 at 16:58, on Zulip):

@Taylor Cramer you mentioned having a big PR incoming, is it https://github.com/rust-lang/async-book/pull/18 ?

Taylor Cramer (Jun 14 2019 at 16:58, on Zulip):

indeed

nikomatsakis (Jun 14 2019 at 16:58, on Zulip):

btw async-book#18 should work now ;)

Taylor Cramer (Jun 14 2019 at 16:59, on Zulip):

fancy

nikomatsakis (Jun 14 2019 at 16:59, on Zulip):

But @Taylor Cramer I was hoping to get a better idea what you think is the "key thing" that closer understanding of the Future trait provides. You mentioned that you felt like it was important to helping unconfuse people

nikomatsakis (Jun 14 2019 at 17:00, on Zulip):

(I'm wondering if there is some simplified version of the intution that can be given more easily, with the full details deferred for later)

Taylor Cramer (Jun 14 2019 at 17:01, on Zulip):

Hm, I'm curious what the full details you have in mind are that you think we could omit

Taylor Cramer (Jun 14 2019 at 17:02, on Zulip):

I think it's really important to cover the execution model (how futures are scheduled, what happens when you poll them, how they resolve etc.)

Taylor Cramer (Jun 14 2019 at 17:02, on Zulip):

as well as how the combinators work via delegating to child futures

Taylor Cramer (Jun 14 2019 at 17:03, on Zulip):

and giving an intuition for how the same principle applies to async/await code

Taylor Cramer (Jun 14 2019 at 17:03, on Zulip):

I've found that trying to handwave "it's like javascript except if you don't await it it doesn't do anything" to not work very well

nikomatsakis (Jun 14 2019 at 17:03, on Zulip):

where does that break down?

Taylor Cramer (Jun 14 2019 at 17:03, on Zulip):

there're too many holes around e.g. futures all being different types, how they're actually getting run, etc.

Taylor Cramer (Jun 14 2019 at 17:04, on Zulip):

and that stuff all falls out more naturally if folks understand the structure of the state machines

nikomatsakis (Jun 14 2019 at 17:05, on Zulip):

Really interesting.

nikomatsakis (Jun 14 2019 at 17:05, on Zulip):

I could imagine trying to convey some sense of the "polling" model

nikomatsakis (Jun 14 2019 at 17:05, on Zulip):

in a more high-level way

Taylor Cramer (Jun 14 2019 at 17:06, on Zulip):

You think the current TimerFuture and "build an executor" examples are too lengthy?

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

I mean in the end I think it's fine to show the details too

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

(I haven't read those examples yet)

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

I mean in the end I think it's fine to show the details too

people will definitely want to learn these!

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

I just imagine that it'll work better if you come to it

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

after you've played around a bit with async-await

nikomatsakis (Jun 14 2019 at 17:06, on Zulip):

maybe even being exposed to some of those gaps

Taylor Cramer (Jun 14 2019 at 17:07, on Zulip):

my experience has been that people get pretty frustrated trying to write async/await code if they haven't taken the time to understand how futures work

Taylor Cramer (Jun 14 2019 at 17:07, on Zulip):

it's a pretty leaky abstraction

nikomatsakis (Jun 14 2019 at 17:07, on Zulip):

well you definitely have more experience with watching people do that (and doing it!) than I do

nikomatsakis (Jun 14 2019 at 17:07, on Zulip):

though I'd love to have some specific examples (it's hard to do that, I know) of the kinds of things people get confused about

Taylor Cramer (Jun 14 2019 at 17:08, on Zulip):

but I could also imagine encouraging patterns that make people less likely to hit rough edges, e.g. boxing everywhere at first

nikomatsakis (Jun 14 2019 at 17:08, on Zulip):

I've only written a small amount, so I guess my own experiences are not represenstative

nikomatsakis (Jun 14 2019 at 17:08, on Zulip):

so far I've not really had to know about the model (but of course I also kind of do)

nikomatsakis (Jun 14 2019 at 17:08, on Zulip):

but I could also imagine encouraging patterns that make people less likely to hit rough edges, e.g. boxing everywhere at first

yes so .. one thing that @boats brought up was that people might have to know about pin (at present, at least) to use select, or maybe some other combinators

nikomatsakis (Jun 14 2019 at 17:09, on Zulip):

I'd definitely expect boxing as a reasonable starting point

Taylor Cramer (Jun 14 2019 at 17:09, on Zulip):

indeed

Taylor Cramer (Jun 14 2019 at 17:09, on Zulip):

select! is unfortunately complex for a number of reasons

nikomatsakis (Jun 14 2019 at 17:10, on Zulip):

I feel like the book is a good .. way for us to help understand the overall "ergonomic picture"

nikomatsakis (Jun 14 2019 at 17:10, on Zulip):

Btw, cc @Florian Gilcher -- who was it you were saying we should talk to re: async-book?

Taylor Cramer (Jun 14 2019 at 17:12, on Zulip):

a good way for us to understand the overall ergonomic picture

nikomatsakis (Jun 14 2019 at 17:12, on Zulip):

ps I'm going to merge async-book#18 .. seems good?

Taylor Cramer (Jun 14 2019 at 17:13, on Zulip):

@nikomatsakis works for me (cc @Yoshua Wuyts )

Taylor Cramer (Jun 14 2019 at 17:14, on Zulip):

it's gonna be annoying having to update all those line numbers every time we make a change ;)
It'll be a good incentive to keep examples small and in their own crates :)

Taylor Cramer (Jun 14 2019 at 17:15, on Zulip):

a good way for us to understand the overall ergonomic picture

yeah, I'm going to expand on some of the later sections, and I'm hoping that will help add some clarity around where some of the unavoidable ergonomic burdens are

nikomatsakis (Jun 14 2019 at 18:23, on Zulip):

@Taylor Cramer to start I'm going to open a PR with a more minimal version of my proposal =)

centril (Jun 14 2019 at 20:26, on Zulip):

@nikomatsakis @Taylor Cramer maybe it would be good to describe the execution model in a pictorial form?

nikomatsakis (Jun 14 2019 at 21:55, on Zulip):

@centril sounds good

nikomatsakis (Jun 14 2019 at 21:55, on Zulip):

I feel like there should be some way to explain the model without (e.g.) talking about Waker

nikomatsakis (Jun 14 2019 at 21:56, on Zulip):

but I'm not sure :)

nikomatsakis (Jun 14 2019 at 21:56, on Zulip):

I'd still like to better understand what kind of unexpected leaks occur

Taylor Cramer (Jun 17 2019 at 16:47, on Zulip):

I'd still like to better understand what kind of unexpected leaks occur

Is there a reason you expect unexpected leaks?

Taylor Cramer (Jun 17 2019 at 16:48, on Zulip):

oh, "leaks" as in the abstraction

nikomatsakis (Jun 17 2019 at 20:39, on Zulip):

right I just mean I want to understand more examples of what kind of confusion arises and what parts of the futures model explanation cleared it up. It seems to me like saying "futures are lazy, you await them or spawn them" would cover it, but I believe you when you say it does't

Giles Cope (Jul 24 2019 at 09:02, on Zulip):

For me the confusion or rather lack of documentation is on examples of constructing Streams and whether one can construct a stream from a series (Vec?) of Futures. I think also showing the desugering in the book is a good way to demystify things.

Taylor Cramer (Aug 13 2019 at 21:11, on Zulip):

@Giles Cope what desugaring are you referring to?

Giles Cope (Aug 27 2019 at 16:40, on Zulip):

Showing how an async call is turned into an impl Future signature. I'm pretty sure your going to cover that though. Now I think my main questions are whether https://github.com/dtolnay/async-trait or https://github.com/taiki-e/futures-async-stream or something else is going to be a good stop-gap for creating streams. Would be good to point out the efforts out there.

nikomatsakis (Aug 27 2019 at 16:42, on Zulip):

yeah, documenting #[async_trait] in general seems good

Last update: Nov 15 2019 at 09:45UTC