This is a draft "status quo" story submitted as part of the brainstorming period. It is derived from real-life experiences of actual Rust users and is meant to reflect some of the challenges that Async Rust programmers face today.
If you would like to expand on this story, or adjust the answers to the FAQ, feel free to open a PR making edits (but keep in mind that, as they reflect peoples' experiences, status quo stories cannot be wrong, only inaccurate). Alternatively, you may wish to add your own status quo story!
Niklaus, who sometimes goes by the pen name "Starol Klichols", has authored some long-form documentation about Rust that people have found helpful. One could even go so far as to call this documentation a "book".
Niklaus has typically minimized the use of crates in documentation like this as much as possible. Niklaus has limited time to dedicate to keeping the documentation up to date, and given the speed at which the ecosystem sometimes evolves, it's hard to keep up when crates are involved. Also, Niklaus would like to avoid limiting the readership of the documentation to the users of a particular crate only, and would like to avoid any accusations of favoritism.
But Niklaus would really really like to document async to avoid disappointing people like Barbara!
Niklaus was excited about the RFC proposing that
block_on be added to the stdlib, because it seemed like that would solve Niklaus' problems. Niklaus would really like to include
async in a big update to the documentation. No pressure.
Writing documentation to go with the language/stdlib for something that is half in the language/stdlib and half in the ecosystem is hard. This is related to Barbara's story about wanting to get started without needing to pick an executor. There are topics of async that apply no matter what executor you pick, but it's hard to explain those topics without picking an executor to demonstrate with. We all have too much work to do and not enough time.
- It me and Steve. Surprise!
- We've wanted to add async to the book for a long time.
- So far, we use exactly one crate in the book,
rand, and a recent update to
randcaused readers confusion and caused a bunch of work on our part. Take a look at all the issues linked to this PR. I really really really don't want to use more crates in the book.
Niko said I couldn't add new characters.
I happen to know that the next version of Programming Rust, whose authors might be described as different characters, includes
async and uses
async-std. So it's possible to just pick an executor and add async to the book, but I don't wanna.