Stream: wg-async-foundations/book

Topic: experience report


nikomatsakis (Aug 14 2019 at 17:33, on Zulip):

so I had a good conversation @Jack Moffitt recently, who was telling me of their difficulties getting started with the async book

nikomatsakis (Aug 14 2019 at 17:34, on Zulip):

it seemed like a lot of it stemmed from (a) it being hard and confusing to figure out which versions of everything to be using; (b) the hello world examples don't spell out enough stuff like "which feature gate to use" and which version of futures crate; (c) the futures crate itself that is most prominently on docs.rs is 0.1.28 which includes its own version of Future and doesn't have many of the fns that appear in the book

nikomatsakis (Aug 14 2019 at 17:35, on Zulip):

anyway I asked them to come and jot some notes here

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

sounds like useful feedback! I'm excited to hear more

nikomatsakis (Aug 14 2019 at 17:55, on Zulip):

I think this message from internals perhaps captures the "essence" of @Jack Moffitt's experience, if not the details.

Taylor Cramer (Aug 14 2019 at 18:10, on Zulip):

I still remain excited about async in rust, but feel like I need to wait a few more months for the ecosystem to continue to build out and up

sounds like a reasonable summary to me

Taylor Cramer (Aug 14 2019 at 18:10, on Zulip):

I wouldn't expect anything different

Taylor Cramer (Aug 14 2019 at 18:10, on Zulip):

but I am interested to know about details of the book that could've helped in the problem-solving

Jack Moffitt (Aug 14 2019 at 18:12, on Zulip):

That internals message is indeed, similar, but he made it farther than I did.

My experience started with a teammate reporting a strange compiler error. Specifically there was a function that returned impl Future<Output = ()> and he was trying to return future::ok::<(),()>(()). I first looked at the docs, which I found via Google. They showed that future::ok returned FutureResult and that FutureResult impled Future, so the code looked fine, even though it wouldn't compile. It was clear after a bit of digging that these were outdated or perhaps newer docs.

Next I decided I'd mock this up on the playground and see what happened, but I couldn't get anything to compile. That wasn't too surprising, since I hadn't written any async code before in Rust. I then went to the async book and decided I'd just start from the beginning until I got something simple working, which I could then progress to a simplified example of the future::ok thing.

Here I got stuck because executor::block_on didn't exist, and nothing I did seemed to help. I started trying to figure out which version of futures i needed, whether I needed tokio or not, etc. And there I stopped for the evening.

Jack Moffitt (Aug 14 2019 at 18:17, on Zulip):

but I am interested to know about details of the book that could've helped in the problem-solving

One thing is that none of the examples run in the playground. They give approximately the same errors I was getting, which makes it seem like the book is out of date. Fixing that will help.

I also think having some kind of Chapter 0 that addresses this transition period would be helpful. Here's what you need to try this out now, and here are the major libs involved and their current state. And keep that page as up to date as possible. Part of my problem is there is no foothold to start to build my knowledge base. I know only that a) std::future::Future is stable, async and .await will soon be stable (and are currently supported in nightly), and beyond that I have no idea which libraries will be needed/useful and the difference between the state right now and the desired end state.

It appears I need to be using futures-preview, feature(async_await), and aside from toy examples, some runtime like the runtime crate or tokio.

Taylor Cramer (Aug 14 2019 at 18:19, on Zulip):

One thing is that none of the examples run in the playground. They give approximately the same errors I was getting, which makes it seem like the book is out of date. Fixing that will help.

The book isn't out of date-- it seems like you weren't using the correct version of hte futures-preview crate

Taylor Cramer (Aug 14 2019 at 18:19, on Zulip):

or weren't using futures-preview at all

Taylor Cramer (Aug 14 2019 at 18:19, on Zulip):

the examples cannot be made to work on the playground because the playground does not include futures-preview

Jack Moffitt (Aug 14 2019 at 18:19, on Zulip):

I wasn't using it at all, which is part of hte problem. Where was I supposed to learn about this? I realize now I can get to the book's example code repo and see it there, but the book doesn't talk about this.

Taylor Cramer (Aug 14 2019 at 18:20, on Zulip):

in the very first example there is a sample of what your cargo.toml should look like: https://rust-lang.github.io/async-book/01_getting_started/05_http_server_example.html

Taylor Cramer (Aug 14 2019 at 18:20, on Zulip):

It also describes how to get the proper version of rustc using rustup

Taylor Cramer (Aug 14 2019 at 18:21, on Zulip):

Is there another way this could have been communicated more clearly?

Taylor Cramer (Aug 14 2019 at 18:24, on Zulip):

(all the "applied" sections have similar Cargo.toml samples)

Jack Moffitt (Aug 14 2019 at 18:24, on Zulip):

I gave up on the page before that one, that had the hello world example I couldn't get to work. https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html

I see there is a "State of Asynchronous Rust" page already there, but it is written as if I know what lots of these things are and does not mention futures-preview.

Taylor Cramer (Aug 14 2019 at 18:25, on Zulip):

Okay. Those were only intended as examples and not as runnable code, but it seems like that was confusing so perhaps that section should be amended to include a Cargo.toml as well

Jack Moffitt (Aug 14 2019 at 18:30, on Zulip):

My suggestion is perhaps reordering that stuff a bit. Make a Chapter 0 which is "The State of Asynchronous Rust". Spurce that up a bit so it's more newbie friendly. Describe the major players, the desired end state (as it is understood right now), and the current state. Then show exactly what's needed to get the stuff from the book to work, that is necessary now but wouldn't necessarily be needed in the future.

Can we turn off run buttons and such until those will work? Can we update playground to work with the ideal current state?

Maybe we can make a special note on each page pointing back at chapter 0 saying "Asynchronous Rust is in active development, and is not yet done. If you have any trouble with the examples here, please make sure you read or re-read Chapter 0 which describes how to use async Rust during this transition period."

Taylor Cramer (Aug 14 2019 at 18:36, on Zulip):

There's an open issue about the run buttons. I don't have a way to control that that I know of, but it is worthy of investigation. I also don't have a way to control which crates appear in the playground, and I don't think it would be correct for the playground to start using futures 0.3 anyways until async/await is stable

Taylor Cramer (Aug 14 2019 at 18:36, on Zulip):

once async/await staabilizes and futures-preview is released as futures 0.3, that problem will solve itself

Jack Moffitt (Aug 14 2019 at 18:37, on Zulip):

If you think that could work, I can try drafting a PR. I'm happy to pitch in here.

Taylor Cramer (Aug 14 2019 at 18:41, on Zulip):

The State of Asynchronous Rust

there already is a section under this name-- feel free to send PRs to add things to it if you think it's unclear

Taylor Cramer (Aug 14 2019 at 18:42, on Zulip):

in general feel free to open PRs or issues for any difficulties you're experiencing or ideas you have

Taylor Cramer (Aug 14 2019 at 18:42, on Zulip):

and I'll do my best to respond in a timely manner

Last update: Nov 15 2019 at 09:40UTC