add a pair of stories about how we could have a default runtime but allow you to change back and forth

Author: nikomatsakis

src/vision/shiny_future/alan_switches_runtimes.md

@@ -0,0 +1,148 @@
+# ✨ Shiny future stories: template
+
+[How To Vision: Shiny Future]: ../how_to_vision/shiny_future.md
+[the raw source from this template]: https://raw.githubusercontent.com/rust-lang/wg-async-foundations/master/src/vision/shiny_future/template.md
+[`shiny_future`]: https://github.com/rust-lang/wg-async-foundations/tree/master/src/vision/shiny_future
+[`SUMMARY.md`]: https://github.com/rust-lang/wg-async-foundations/blob/master/src/SUMMARY.md
+
+## 🚧 Warning: Draft status 🚧
+
+This is a draft "shiny future" story submitted as part of the brainstorming period. It is derived from what actual Rust users wish async Rust should be, and is meant to deal with 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 peoples needs and desires for async Rust may differ greatly, shiny future stories [cannot be wrong]. At worst they are only useful for a small set of people or their problems might be better solved with alternative solutions). Alternatively, you may wish to [add your own shiny vision story][htvsq]!
+
+## The story
+
+Since his [early adventures](./alans_trust_in_the_compiler_is_rewarded.md) with Async I/O went so well, Alan has been looking for a way to learn more. He finds a job working in Rust. One of the projects he works on is [DistriData]. Looking at their code, he sees an annotation he has never seen before:
+
+```rust
+#[async_runtime(humboldt)]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let result = std::async_thread::spawn(async move {
+        do_something()
+    });
+}
+```
+
+He asks Barbara, one of his coworkers, "What is this `async_runtime` annotation? And what's `humboldt`?" She answers by explaining to him that Rust's support for async I/O is actually based around an underlying runtime. "Rust gives you a pretty decent runtime by default," she says, "but it's not tuned for our workloads. We wrote our own runtime, which we call `humboldt`."
+
+[DistriData]: ../projects/DistriData.md
+
+Alan asks, "What happens with the various std APIs? For example, I see we are calling `std::async_thread::spawn` -- when I used that before, it spawned tasks into the default runtime. What happens now?"
+
+Barbara explains that the "async" APIs in std generally execute relative to the current runtime that is in use. "When you call `std::async_thread::spawn`, it will spawn a task onto the current runtime. It's the same with the routines in `std::async_io` and and so forth. The `async_runtime` annotation just affects which runtime runs the `main` function, everything else follows from there."
+
+## Learning more about Humboldt
+
+Alan sees that some of the networking code that is being used in their application is creating network connections using humboldt APIs:
+
+```rust
+use humboldt::network;
+```
+
+He asks Barbara, "Why don't we use the `std::async_io` APIs for that?" She explains that Humbolt makes use of some custom kernel extensions that, naturally enough, aren't part of the std library. "TCP is for rubes," she says, "we are using TTCP -- Turbo TCP." Her mind wanders briefly to [Turbo Pascal] and she has a brief moment of yearning for the days when computers had a "Turbo" button that changed them from 8 MHz to 12 MHz. She snaps back into the present day. "Anyway, the `std::async_io` APIs just call into humboldt's APIs via various traits. But we can code directly against `humboldt` when we want to access the extra capabilities it offers."
+
+[Turbo Pascal]: https://en.wikipedia.org/wiki/Turbo_Pascal
+
+## Integrating into other event loops
+
+Later on, Alan is working on a visualizer front-end that integrates with [DistriData] to give more details about their workloads. To do it, he needs to integrate with Cocoa APIs and he wants to run certain tasks on Grand Central Dispatch. He approaches Barbara and asks, "If everything is running on `humboldt`, is there a way for me to run some things on another event loop? How does that work?"
+
+Barbara explains, "That's easy. You just have to use the `gcd` wrapper crate -- you can find it on `crates.io`. It implements the runtime traits for `gcd` and it has a `spawn` method. Once you spawn your task onto `gcd`, everything you run within gdb will be running in that context."
+
+Alan says, "And so, if I want to get things running on `humboldt` again, I spawn a task back on `humboldt`?"
+
+"Exactly," says Barbara. "Humboldt has a global event loop, so you can do that by just doing `humboldt::spawn`. You can also just use the `humboldt::io` APIs directly and so forth if you want to do I/O with humboldt."
+
+Alan winds up with some code that looks like this:
+
+```rust
+async fn do_something_on_humboldt() {
+    gcd::spawn(async move {
+        let foo = do_something_on_gcd();
+
+        let bar = humboldt::spawn(async move {
+            do_a_little_bit_of_stuff_on_humboldt();
+        });
+
+        combine(foo.await, bar.await);
+    });
+}
+```
+
+## 🤔 Frequently Asked Questions
+
+### What status quo story or stories are you retelling?
+
+Good question! I'm not entirely sure! I have to go looking and think about it. Maybe we'll have to write some more.
+
+### What are the key points you were trying to convey with this status quo story?
+
+* There is some way to seamlessly change to a different default runtime to use for `async main`.
+* There is no global runtime, just the current runtime.
+* When you are using this different runtime, you can write code that is hard-coded to it and which exposes additional capabilities.
+* You can integrate multiple runtimes relatively easily, and the std APIs work with whechever is the current runtime.
+
+### How do you imagine the std APIs and so forth know the current runtime?
+
+I was imagining that we would add fields to the `Context<'_>` struct that is supplied to each `async fn` when it runs. Users don't have direct access to this struct, but the compiler does. If the std APIs return futures, they would gain access to it that way as well. If not, we'd have to create some other mechanism.
+
+### What happens for runtimes that don't support all the features that std supports?
+
+That feels like a portability question. See the (yet to be written) sequel story, "Alan runs some things on WebAssembly". =)
+
+### **What is [Alan] most excited about in this future? Is he disappointed by anything?**
+
+Alan is excited about how easy it is to get async programs up and running, and he finds that they perform pretty well once he does so, so he's happy.
+
+### **What is [Grace] most excited about in this future? Is she disappointed by anything?**
+
+Grace is concerned with memory safety and being able to deploy her tricks she knows from other languages. Memory safety works fine here. In terms of tricks she knows and loves, she's happy that she can easily switch to another runtime. The default runtime is good and works well for most things, but for the [`DistriData`] project, they really need something tailored just for them. She is also happy she can use the extended APIs offered by `humboldt`.
+
+### **What is [Niklaus] most excited about in this future? Is he disappointed by anything?**
+
+Niklaus finds it async Rust quite accessible, for the same reasons cited as in ["Alan's Trust in the Rust Compiler is Rewarded"].
+
+["Alan's Trust in the Rust Compiler is Rewarded"]: ../alans_trust_in_the_compiler_is_rewarded.md
+
+### **What is [Barbara] most excited about in this future? Is she disappointed by anything?**
+
+Depending on the technical details, Barbara may be a bit disappointed by the details of how std interfaces with the runtimes, as that may introduce some amount of overhead. This may not matter in practice, but it could also lead to library authors avoiding the std APIs in favor of writing generics or other mechanisms that are "zero overhead".
+
+### **What [projects] benefit the most from this future?**
+
+Projects like [DistriData] really benefit from being able to customize their runtime.
+
+### **Are there any [projects] that are hindered by this future?**
+
+We have to pay careful attention to embedded projects like [MonsterMesh]. Some of the most obvious ways to implement this future would lean on `dyn` types and perhaps boxing, and that would rule out embedded projects. Embedded runtimes like [embassy] are also the most different in their overall design and they would have the hardest time fitting into the std APIs (of course, many embedded projects are already no-std, but many of them make use of some subset of the std capabilities through the facade).
+
+[MonsterMesh]: ../projects/MonsterMesh.md
+[embassy]: https://github.com/akiles/embassy
+
+### **What are the incremental steps towards realizing this shiny future?**
+
+There are a few steps required to realize this future:
+
+* We have to determine the core mechanism that is used for std types to interface with the current scheduler. 
+    * Is it based on dynamic dispatch? Delayed linking? Some other tricks we have yet to invent?
+    * Depending on the details, language changes may be required. 
+* We have to hammer out the set of traits or other interfaces used to define the parts of a runtime (see below for some of the considerations).
+    * We can start with easier cases and proceed to more difficult ones, however.
+
+### **Does realizing this future require cooperation between many projects?**
+
+Yes. We will need to collaborate to define traits that std can use to interface with each runtime, and the runtimes will need to implement those traits. This is going to be non-trivial, because we want to preserve the ability for independent runtimes to experiment, while also preserving the ability to "max and match" and re-use components. For example, it'd probably be useful to have a bunch of shared I/O infrastructure, or to have utility crates for locks, for running threadpools, and the like. On the other hand, tokio takes advantage of the fact that it owns the I/O types *and* the locks *and* the scheduler to do some [nifty tricks](https://tokio.rs/blog/2020-04-preemption) and we would want to ensure that remains an option.
+
+### Is this story 
+
+[character]: ../characters.md
+[comment]: ./comment.md
+[status quo stories]: ./status_quo.md
+[Alan]: ../characters/alan.md
+[Grace]: ../characters/grace.md
+[Niklaus]: ../characters/niklaus.md
+[Barbara]: ../characters/barbara.md
+[projects]: ../projects.md
+[htvsq]: ../how_to_vision/shiny_future.md
+[cannot be wrong]: ../how_to_vision/comment.md#comment-to-understand-or-improve-not-to-negate-or-dissuade

src/vision/shiny_future/alans_trust_in_the_compiler_is_rewarded.md

@@ -0,0 +1,199 @@
+# ✨ Shiny future stories: template
+
+[How To Vision: Shiny Future]: ../how_to_vision/shiny_future.md
+[the raw source from this template]: https://raw.githubusercontent.com/rust-lang/wg-async-foundations/master/src/vision/shiny_future/template.md
+[`shiny_future`]: https://github.com/rust-lang/wg-async-foundations/tree/master/src/vision/shiny_future
+[`SUMMARY.md`]: https://github.com/rust-lang/wg-async-foundations/blob/master/src/SUMMARY.md
+
+## 🚧 Warning: Draft status 🚧
+
+This is a draft "shiny future" story submitted as part of the brainstorming period. It is derived from what actual Rust users wish async Rust should be, and is meant to deal with 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 peoples needs and desires for async Rust may differ greatly, shiny future stories [cannot be wrong]. At worst they are only useful for a small set of people or their problems might be better solved with alternative solutions). Alternatively, you may wish to [add your own shiny vision story][htvsq]!
+
+## The story
+
+### Trust the compiler
+Alan has a lot of experience in C#, but in the meantime has created some successful projects in Rust.
+He has dealt with his fair share of race conditions/thread safety issues during runtime in C#, but is now starting to trust that if his Rust code compiles,
+he won't have those annoying runtime problems to deal with.
+
+This allows him to try to squeeze his programs for as much performance as he wants, because the compiler will stop him when he tries things that could result in runtime problems.
+After seeing the performance and the lack of runtime problems, he starts to trust the compiler more and more with each project finished.
+
+He knows what he can do with external libraries, he does not need to fear concurrency issues if the library cannot be used from multiple threads, because the compiler would tell him.
+
+His trust in the compiler solidifies further the more he codes in Rust.
+
+### The first async project
+
+Alan now starts with his first async project. He opens up the Rust book to the "Async I/O" chapter and it guides him to writing his first program. He starts by writing some synchronous code to write to the file system:
+
+```rust,ignore
+use std::fs::File;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut file = File::create("a.txt")?;
+    file.write_all(b"Hello, world!")?;
+    Ok(())
+}
+```
+
+Next, he adapts that to run in an async fashion. He starts by converting `main` into `async fn main`:
+
+```rust,ignore
+use std::fs::File;
+
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut file = File::create("a.txt")?;
+    file.write_all(b"Hello, world!")?;
+    Ok(())
+}
+```
+
+The code compiles, but he gets a warning:
+
+```
+warning: using a blocking API within an async function
+ --> src/main.rs:4:25
+1 | use std::fs::File;
+  |     ------------- try changing to `std::async_io::fs::File`
+  | ...
+4 |     let mut file: u32 = File::create("a.txt")?;
+  |                         ^^^^^^^^^^^^ blocking functions should not be used in async fn
+help: try importing the async version of this type
+ --> src/main.rs:1
+1 | use std::async_fs::File;
+```
+
+"Oh, right," he says, "I am supposed to use the async variants of the APIs." He applies the suggested fix in his IDE, and now his code looks like:
+
+```rust
+use std::async_fs::File;
+
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut file = File::create("a.txt")?;
+    file.write_all(b"Hello, world!")?;
+    Ok(())
+}
+```
+
+His IDE recompiles instantaneously and he now sees two little squiggles, one under each `?`. Clicking on the errors, he sees:
+
+```
+error: missing await
+ --> src/main.rs:4:25
+4 |     let mut file: u32 = File::create("a.txt")?;
+  |                                              ^ returns a future, which requires an await
+help: try adding an await
+ --> src/main.rs:1
+4 |     let mut file: u32 = File::create("a.txt").await?;
+```
+
+He again applies the suggested fix, and his code now shows:
+
+```rust
+use std::async_fs::File;
+
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut file = File::create("a.txt").await?;
+    file.write_all(b"Hello, world!").await?;
+    Ok(())
+}
+```
+
+Happily, it compiles, and when he runs it, everything works as expected. "Cool," he thinks, "this async stuff is pretty easy!"
+
+### Making some web requests
+
+Next, Alan decides to experiment with some simple web requests. This isn't part of the standard library, but the `fetch_rs` package is listed in the Rust book. He runs `cargo add fetch_rs` to add it to his `Cargo.toml` and then writes:
+
+```rust
+use std::async_fs::File;
+use fetch_rs;
+
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut file = File::create("a.txt")?;
+    file.write_all(b"Hello, world!")?;
+
+    let body = fetch_rs::get("https://www.rust-lang.org")
+        .await?
+        .text()
+        .await?;
+    println!("{}", body);
+
+    Ok(())
+}
+```
+
+This feels pretty easy!
+
+## 🤔 Frequently Asked Questions
+
+### What status quo story or stories are you retelling?
+
+* [Alan started trusting the Rust compiler, but then async](../status_quo/alan_started_trusting_the_rust_compiler_but_then_async.md)
+
+### What are the key points you were trying to convey with this status quo story?
+
+* Getting started with async should be as automated as possible:
+    * change `main` to an `async fn`;
+    * use the APIs found in modules like `std::async_foo`, which should map as closely as possible to their non-async equivalents.
+* You should get some sort of default runtime that is decent
+* Lints should guide you in using async:
+    * identifying blocking functions
+    * identifying missing `await`
+* You should be able to grab libraries from the ecosystem and they should integrate with the default runtime without fuss
+
+### Is there a "one size fits all" runtime in this future?
+
+This particular story doesn't talk about what happens when the default runtime isn't suitable. But you may want to read its sequel, ["Alan Switches Runtimes"](./alan_switches_runtimes.md).
+
+### **What is [Alan] most excited about in this future? Is he disappointed by anything?**
+
+Alan is excited about how easy it is to get async programs up and running. He also finds the performance is good. He's good.
+
+### **What is [Grace] most excited about in this future? Is she disappointed by anything?**
+
+Grace is happy because she is getting strong safety guarantees and isn't getting surprising runtime panics when composing libraries. The question of whether she's able to use the tricks she knows and loves is a good one, though. The default scheduler may not optimize for maximum performance -- this is something to explore in future stories. The ["Alan Switches Runtimes"](./alan_switches_runtimes.md), for example, talks more about the ability to change runtimes.
+
+### **What is [Niklaus] most excited about in this future? Is he disappointed by anything?**
+
+Niklaus is quite happy. Async Rust is fairly familiar and usable for him. Further, the standard library includes "just enough" infrastructure to enable a vibrant crates-io ecosystem without centralizing everything.
+
+### **What is [Barbara] most excited about in this future? Is she disappointed by anything?**
+
+Barbara quite likes that the std APIs for sync and sync fit together, and that there is a consistent naming scheme across them. She likes that there is a flourishing ecosystem of async crates that she can choose from.
+
+### **What [projects] benefit the most from this future?**
+
+A number of projects benefit:
+
+* Projects like [YouBuy] are able to get up and going faster.
+* Libraries like [SLOW] become easier because they can target the std APIs and there is a defined plan for porting across runtimes.
+
+[YouBuy]: ../projects/YouBuy.md
+[SLOW]: ../projects/SLOW.md
+
+### **Are there any [projects] that are hindered by this future?**
+
+It depends on the details of how we integrate other runtimes. If we wound up with a future where most libraries are "hard-coded" to a single default runtime, this could very well hinder any number of projects, but nobody wants that.
+
+### **What are the incremental steps towards realizing this shiny future?**
+
+This question can't really be answered in isolation, because so much depends on the story for how we integrate with other runtimes. I don't think we can accept a future where is literally a single runtime that everyone has to use, but I wanted to pull out the question of "non-default runtimes" (as well as more details about the default) to other stories.
+
+### **Does realizing this future require cooperation between many projects?**
+
+Yes. For external libraries like `fetch_rs` to interoperate they will want to use the std APIs (and probably traits).
+
+[character]: ../characters.md
+[comment]: ./comment.md
+[status quo stories]: ./status_quo.md
+[Alan]: ../characters/alan.md
+[Grace]: ../characters/grace.md
+[Niklaus]: ../characters/niklaus.md
+[Barbara]: ../characters/barbara.md
+[projects]: ../projects.md
+[htvsq]: ../how_to_vision/shiny_future.md
+[cannot be wrong]: ../how_to_vision/comment.md#comment-to-understand-or-improve-not-to-negate-or-dissuade