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
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.
(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)
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"
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
also, basic documentation on how to work with pinned variables, like using
Found 2 confusing things, but nothing serious.
@Nemo157 what would be a case where users need a Pin?
most commonly when working with generic
impl Future is taken care of in async/await by
.await, but having to pin a stream is not uncommon
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
probably the major thing is trying to return boxed futures,
Box<dyn Future> is unusable, which is why there's the
BoxFuture type alias
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
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
where it seemed like they hit a number of confusing things that they overcame but where docs would have been useful
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
2. developing an intuitution as to when you need to use
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.
@nikomatsakis did they make public posts, or is that just from discussion?
oh, just private discussion
(I don't know any details, the only thing I remember had to do w/ boxed)
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
Yup, I'd love if we could have
Unpin point to
Box::pin, but unfortunately the former is a 3p crate, so that wouldn't work out
@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.
@David Barsky fwiw it used to be
before it got pulled out into a separate crate
@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.
it could at least be re-exported since it's almost always useful to users
regarding pointing to
pin_mut!—could a clippy lint provide that information?
not sure how clippy would help since once you run clippy you've already got it compiling
RE "not sure of the reasoning" it's because
pin_utils is all general-purpose utils for Pin
they don't interact directly with
std::future/task at all
ah, yes—true about the reasoning. forgot about non-futures use-cases for Pin.
@David Barsky I think _most_ people can waste an allocation, it's totally fair for beginners documentation to go down that route.
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