Stream: wg-async-foundations

Topic: end-user docs and futures


nikomatsakis (May 28 2019 at 18:09, on Zulip):

One thing I am wondering about, that relates to what @Florian Gilcher was saying. I've talked to a few people who tried to put async-await to work, and they usually wind up getting stuck in/around the futures library -- e.g., discovering things like the boxed() combinator.

nikomatsakis (May 28 2019 at 18:10, on Zulip):

Based on this, I have the feeling that (a) futures 1.0 stabilization is something we should definitely be paying a lot of attention to in the near future, and (b) there is likely a lot of docs we could write in this area.

nikomatsakis (May 28 2019 at 18:10, on Zulip):

(Another question I'm wondering about is whether we can ask people to just tell us the kinds of things they got confused about and would have like to see documented)

Nemo157 (May 28 2019 at 18:11, on Zulip):

I have definitely noticed this as well on discord, a lot of questions can be answered with "here's the combinator from futures you need"

Florian Gilcher (May 28 2019 at 18:12, on Zulip):

BTW, I ported my standard example from my workshop over to runtime + futures and it works quite nicely. https://github.com/ferrous-systems/rust-three-days-course/blob/master/example/redisish-server/with-runtime/mailbox/src/main.rs

Nemo157 (May 28 2019 at 18:12, on Zulip):

also, basic documentation on how to work with pinned variables, like using Box::pin over Box::new

Florian Gilcher (May 28 2019 at 18:13, on Zulip):

Found 2 confusing things, but nothing serious.

Florian Gilcher (May 28 2019 at 18:13, on Zulip):

@Nemo157 what would be a case where users need a Pin?

Nemo157 (May 28 2019 at 18:13, on Zulip):

most commonly when working with generic impl Future/impl Stream

Nemo157 (May 28 2019 at 18:14, on Zulip):

I guess impl Future is taken care of in async/await by .await, but having to pin a stream is not uncommon

nikomatsakis (May 28 2019 at 18:15, on Zulip):

I am wondering whether we can show a lot of the examples we would need be using runtime's current support -- it certainly seems like we could show the various combinators and things that way

Nemo157 (May 28 2019 at 18:15, on Zulip):

probably the major thing is trying to return boxed futures, Box<dyn Future> is unusable, which is why there's the BoxFuture type alias

nikomatsakis (May 28 2019 at 18:15, on Zulip):

for some more advanced things, like the specifics of dealing with HTTP etc, I guess that depends on whether one is using tokio, tide, etc -- for that we might redirect to the docs from each project

nikomatsakis (May 28 2019 at 18:17, on Zulip):

BTW, I ported my standard example from my workshop over to runtime + futures and it works quite nicely.

I am partly going from "experience reports" from wycats + @Jonathan Turner porting over their nushell project

nikomatsakis (May 28 2019 at 18:17, on Zulip):

where it seemed like they hit a number of confusing things that they overcame but where docs would have been useful

David Barsky (May 28 2019 at 18:20, on Zulip):

Some things I've ran into that I suspect others would also run into are:
1. how to write a trait that returns an Future. I've ended up using BoxFuture.
2. developing an intuitution as to when you need to use Pin, e.g., pin_mut!. I've sidestepped that issue for now in https://github.com/davidbarsky/proto-lambda by using BoxFuture, but that's because I afford a heap allocation. Not everybody can.
3. more generally with async/await—the top-level function _must_ async, hence runtime and friends.

Nemo157 (May 28 2019 at 18:20, on Zulip):

@nikomatsakis did they make public posts, or is that just from discussion?

nikomatsakis (May 28 2019 at 18:21, on Zulip):

oh, just private discussion

nikomatsakis (May 28 2019 at 18:21, on Zulip):

(I don't know any details, the only thing I remember had to do w/ boxed)

Nemo157 (May 28 2019 at 18:23, on Zulip):

Paragraph starting "Some more on pinning overall:" in https://internals.rust-lang.org/t/async-await-experience-reports/10200/14 is a pretty good commentary on current pinning documentation

Taylor Cramer (May 28 2019 at 18:25, on Zulip):

Yup, I'd love if we could have rustc_on_unimplemented for Unpin point to pin_mut! and Box::pin, but unfortunately the former is a 3p crate, so that wouldn't work out

David Barsky (May 28 2019 at 18:25, on Zulip):

@Nemo157 Thanks for the link! I think their experiences with pinning should be front-and-center in the futures documentation. I can see an argument for pin_mut! for being folded in the futures crate.

Taylor Cramer (May 28 2019 at 18:25, on Zulip):

@David Barsky fwiw it used to be

Taylor Cramer (May 28 2019 at 18:26, on Zulip):

before it got pulled out into a separate crate

David Barsky (May 28 2019 at 18:26, on Zulip):

@Taylor Cramer I'm not sure of the reasoning behind that, but absent any other evidence, bringing pin_mut! back into futures would be a win, IMO.

Nemo157 (May 28 2019 at 18:27, on Zulip):

it could at least be re-exported since it's almost always useful to users

David Barsky (May 28 2019 at 18:27, on Zulip):

regarding pointing to pin_mut!—could a clippy lint provide that information?

Taylor Cramer (May 28 2019 at 18:28, on Zulip):

not sure how clippy would help since once you run clippy you've already got it compiling

Taylor Cramer (May 28 2019 at 18:29, on Zulip):

RE "not sure of the reasoning" it's because pin_utils is all general-purpose utils for Pin

Taylor Cramer (May 28 2019 at 18:29, on Zulip):

they don't interact directly with std::future/task at all

David Barsky (May 28 2019 at 18:29, on Zulip):

ah, yes—true about the reasoning. forgot about non-futures use-cases for Pin.

Florian Gilcher (May 28 2019 at 18:35, on Zulip):

@David Barsky I think _most_ people can waste an allocation, it's totally fair for beginners documentation to go down that route.

David Barsky (May 28 2019 at 18:39, on Zulip):

That's true! Unrelated, but it's for that reason I've wanted the ~ operator to return as an alias for Box. The syntactic overhead of Box dissuades people from heap allocating more than they should, IMO

Last update: Nov 18 2019 at 00:40UTC