I am surprised Rust doesn't lean into the type system more for declaring async, as I really like that way of framing it. Admittedly, I'm probably not writing ```impl Future<Output = Result<(), Report>> + 'a``` all that much in practice.
I like fasterthanlime's writeups but it does have one particular bugbear for me, that seems particularly common for Rust (and Python, to be fair) feature writeups: environment-based yak shaving because the author likes the mostly-unrelated library <X>. The very first thing that happens if I try to reproduce this code is a build error for cargo-edit, which is totally unrelated to the feature being taught, yet if I wanted to follow the writeup, I'd have to fix it.
I do really have this bugbear, particularly with Rust tutorials
> I am surprised Rust doesn't lean into the type system more for declaring async, as I really like that way of framing it. Admittedly, I'm probably not writing ```impl Future<Output = Result<(), Report>> + 'a``` all that much in practice.
Futures was stabilized before the async syntax, so this used to be the only way you could do it. But those were definitely the bad old days.
A handful of (brave) developers and library writers wrote async code like this back then when they really needed to, but the vast majority waited for async syntax to stabilize. Those state machines get ugly real fast.
> Futures was stabilized before the async syntax, so this used to be the only way you could do it.
While that's technically true (std::future was in 1.36 and async/await syntax was in 1.39), that's a very short timespan of only a few months. You are probably referring to the multiple years where futures only existed as addon libraries where their design was iterated on before the final design of std::future was settled on.
I stand by my opinion that any kind of documentation or tutorial should pass a validation step where the author does copy/paste of all their commands into a clean Docker container or VM image. If any error happens, your work is not done yet.
If you need to instruct users to install a compiler or an extra tool, so be it. It just must work as-is on a clean system (for which using Docker is easiest for me, but a clean VM or any other alternative is fine too).
Preferably the author doesn't copy and paste: preferably there's a documentation build step where everything gets run, relevant outputs get inserted into the docs, and any errors get caught.
This is how my docs for Zapatos[1] work, for instance. :)
It is probably too much to ask everyone follow the same approach, so I'll be happy if people just test their own commands by hand. But your doc build step that validates code and catches errors? That's the ideal setup, for sure. Great job!
> I stand by my opinion that any kind of documentation or tutorial should pass a validation step where the author does copy/paste of all their commands into a clean Docker container or VM image. If any error happens, your work is not done yet.
Very much this. We often write scientific software with (command-line) instructions for nontechnical or sort-of-technical users and have learned from experience to not assume anything about the user's environment, or background knowledge, and to try to replicate our documentation's instructions line-by-line!
On the other hand, I really like that way of giving "best practice" advice, as it's really useful advice. You end up with a deeper understanding of futures, but also concrete advice that you can apply easily.
Not to worry, we also spend some time messing with strace and GDB. I see it more as "giving a working knowledge of Rust" than a distraction. Some of these crates/tools are lifechangers, I wouldn't want folks to miss out on them.
I'm sorry yodelshady has run into a build error for cargo-edit (was it OpenSSL? screw OpenSSL) but also: the more folks run into these issues and report them, the sooner they're fixed. Also! I think cargo-edit should just be adopted by the default cargo distribution because it's all-around really good.
I have to agree with the first comment: Speaking as someone who was a tech trainer and writer of course materials, tutorial, etc. for a couple of decades, if ``carge-edit`` is not core to what you're trying to teach, leave it out. Get your own desires (ego) out of the way, and stick to teaching what you need to teach. Leave the distractions/side-tracks/proselytising to a separate lesson. You think of the lesson as "Giving a Working Knowledge of Rust"? Great! Then title it accordingly and don't dress it up in "futures" camouflage -- you're doing your readers/learners a disservice.
> Then title it accordingly and don't dress it up in "futures" camouflage -- you're doing your readers/learners a disservice.
In their defense, the title is "Understanding Rust futures by going way too deep", and I think advice and tangents on best practices modules is easily covered by "going way too deep".
> you're doing your readers/learners a disservice.
Not every tutorial needs to be the same, cater to the same type of person, or try to explain things in the same manner. I think the bigger disservice to readers/learners would be to homogenize tutorials into what you think is best. That might work best for a certain type of person at a certain skill level, but that doesn't mean everyone will be served well by that. And as the comments here illustrate, it's not like there's a dearth of Rust futures tutorials and explanations. There's definitely room for a rambling, informal, irreverent, meandering take (it's the only thing that kept me reading until the end, or even past the first page or two).
This isn't a tutorial, nor a training, nor a course though, this is a cave exploration. Its going down the wrong paths, multiple times on purpose. So pack your bag, get your tools in order, we may not return. I really like this style, the wrong paths/side tracks have so much to teach us (more than the right paths).
As someone who's been a technical writer (albeit for years rather than decades), I think this is often good advice, but not here. As other people have pointed out, this isn't trying to be a Futures 101 or Futures for Total Beginners. The title or opening could maybe be clearer about its scope (although I think "way too deep" at least implies the author isn't covering the topic as directly or succinctly as possible), but I think the digressions are interesting to Amos' target audience and part of his style.
I mean, we could also just let the guy write how he wants to write, since we're reading his stuff for free, and we aren't entitled to anything at all from him.
I enjoyed it, and I had never heard of cargo-edit before, and am really glad I now know about it!
I'd say this is a good explanation, but a bad tutorial[1]. Which is fine, they're different things. But if you want it to be a tutorial it should be focused on just Rust Futures, and the other stuff should be separated out.
IMO if your article is long enough that it crashes MobileSafari, it should have a table of contents. Or it should be a book chapter. It’s a really obvious criticism of all of fasterthanlime’s posts that scarcely bears repeating at this point but they’re not getting any shorter. I get that he has a lot to say but I just don’t have time to wade through all of that. What slice of Rust users are both such noobs they haven’t heard of cargo-edit and can’t Google it, but also so advanced they are interested in implementing Future manually to deepen their understanding? It’s ok to teach both things but why together?!
Ok I promise I'm going to stop replying to those comments (because as you pointed out they show up on every post), but! Rust is not the only language with a decent type system out there.
I can definitely see some ML/Haskell/Scala/etc. folks who would quickly pick up on all the Future stuff, drawing parallels with their usual language of choice, yet being completely unaware of all the nice tooling around Rust. It's one of its main selling points for me!
Re cargo-edit specifically, it also lets me stay in flow while writing these: instead of having to repeat "we'll just edit Cargo.toml, make sure to have that under [dependencies], uh this time we need a feature so the right-hand-side needs to be an object, not a string" - instead I can just copy into the article the actual commands I run on my side, and if a quick paragraph about where that subcommand comes from unblocks even one person then it's worth it.
I wouldn’t worry too much about it. You have your style, and it clearly works for the people who like your work. Everyone likes different things, and it doesn’t make sense to force homogeneity. It’s ok to cater to niches.
FWIW, I fall exactly into that niche. I've never written a line of Rust in my life but am quite competent with Haskell and Ruby and have dabbled in at least half a dozen others. Seeing everyday `cargo` use made me think of bundler and the Future/Result type signatures were easy to map onto Async/Either and the like.
So yes, it's a long article but I didn't mind that in the least. Keep it up!
Ignore the naysayers in this thread; I don't really get why people think it's ok nitpick how you've decided to present a particular topic that you publish to the world free of charge. It's... kinda rude, IMO.
I really enjoyed reading this piece, and had never heard of cargo-edit, so thank you for that.
As a Scala person, I've actually struggled with Rust's Future, because it's quite different and requires a new mental model of how things work, which I think you did a great job providing.
> What slice of Rust users are both such noobs they haven’t heard of cargo-edit and can’t Google it, but also so advanced they are interested in implementing Future manually to deepen their understanding?
My colleagues. Many people are skilled programmers jumping into obscure problems with only a baseline level of familiarity with the greater environment.
> What slice of Rust users are both such noobs they haven’t heard of cargo-edit and can’t Google it, but also so advanced they are interested in implementing Future manually to deepen their understanding?
raises hand
I'm not sure how (or why) I'd google cargo-edit, because it's one of those things that you don't even think about until someone tells you about it, and then you're happy they did.
While I certainly wouldn't call myself a Rust expert, I'm no noob either, and am intensely interested in diving deep into topics like this. (Can we also dispense with the gatekeeping put-downs like "noob", please? It's unnecessary and rude.)
> It’s ok to teach both things but why together?!
Because the author felt like it, and since we're consuming his work for free, we're not entitled to tell him how to write?
I like fasterthanlime's writeups but it does have one particular bugbear for me, that seems particularly common for Rust (and Python, to be fair) feature writeups: environment-based yak shaving because the author likes the mostly-unrelated library <X>. The very first thing that happens if I try to reproduce this code is a build error for cargo-edit, which is totally unrelated to the feature being taught, yet if I wanted to follow the writeup, I'd have to fix it.
I do really have this bugbear, particularly with Rust tutorials