Merge pull request #110 from eminence/summary

Update SUMMARY.md and ignore code blocks in stories

Author: rylev

src/SUMMARY.md

@@ -23,10 +23,15 @@
       - [SLOW (Protocol implementation)](./vision/projects/SLOW.md)
    - [😱 Status quo](./vision/status_quo.md)
       - [Template](./vision/status_quo/template.md)
-      - [Alan runs into stack trouble](./vision/status_quo/alan_runs_into_stack_trouble.md)
+      - [Alan finds dropping database handles is hard](./vision/status_quo/alan_finds_database_drops_hard.md)
       - [Alan hates writing a `Stream`](./vision/status_quo/alan_hates_writing_a_stream.md)
+      - [Alan runs into stack trouble](./vision/status_quo/alan_runs_into_stack_trouble.md)
       - [Alan started trusting the Rust compiler, but then... async](./vision/status_quo/alan_started_trusting_the_rust_compiler_but_then_async.md)
+      - [Barbara carefully dismisses embedded `Future`](./vision/status_quo/barbara_carefully_dismisses_embedded_future.md)
       - [Barbara makes their first foray into async](./vision/status_quo/barbara_makes_their_first_steps_into_async.md)
+      - [Barbara plays with async](./vision/status_quo/barbara_plays_with_async.md)
+      - [Barbara tries async streams](./vision/status_quo/barbara_tries_async_streams.md)
+      - [Barbara trims a stacktrace](./vision/status_quo/barbara_trims_a_stacktrace.md)
       - [Grace deploys her service and hits obstacles](./vision/status_quo/grace_deploys_her_service.md)
       - [Niklaus wants to share knowledge](./vision/status_quo/niklaus_wants_to_share_knowledge.md)
    - [✨ Shiny future](./vision/shiny_future.md)

src/vision/status_quo/alan_finds_database_drops_hard.md

@@ -11,7 +11,7 @@ If you would like to expand on this story, or adjust the answers to the FAQ, fee
 
 Alan has been adding an extension to YouBuy that launches a singleton actor which interacts with a Sqlite database using the `sqlx` crate. The Sqlite database only permits a single active connection at a time, but this is not a problem, because the actor is a singleton, and so there only should be one at a time. He consults the documentation for `sqlx` and comes up with the following code to create a connection and do the query he needs:
 
-```rust
+```rust,ignore
 use sqlx::Connection;
 
 #[async_std::main]
@@ -41,7 +41,7 @@ Alan tries to figure out what happened from the logs, but the only information h
 
 He's a bit confused, because he's accustomed to having things generally be cleaned up automatically when they get dropped (for example, dropping a [`File`](https://doc.rust-lang.org/std/fs/struct.File.html) will close it). Searching the docs, he sees the [`close`](https://docs.rs/sqlx/0.5.1/sqlx/trait.Connection.html#tymethod.close) method, but the comments confirm that he shouldn't have to call it explicitly: "This method is not required for safe and consistent operation. However, it is recommended to call it instead of letting a connection drop as the database backend will be faster at cleaning up resources." Still, just in case, he decides to add a call to `close` into his code. It does seem to help some, but he is still able to reproduce the problem if he refreshes often enough. Feeling confused, he adds a log statement right before calling `close` to see if it is working:
 
-```rust
+```rust,ignore
 use sqlx::Connection;
 
 #[async_std::main]

src/vision/status_quo/barbara_carefully_dismisses_embedded_future.md

@@ -36,7 +36,7 @@ kernel does not expose a Future-based interface, so Barbara has to implement
 `Future` by hand rather than using async/await syntax. She starts with a
 skeleton:
 
-```rust
+```rust,ignore
 /// Passes `buffer` to the kernel, and prints it to the console. Returns a
 /// future that returns `buffer` when the print is complete. The caller must
 /// call kernel_ready_for_callbacks() when it is ready for the future to return. 
@@ -61,7 +61,7 @@ Note: All error handling is omitted to keep things understandable.
 
 Barbara begins to implement `print_buffer`:
 
-```rust
+```rust,ignore
 fn print_buffer(buffer: &'static mut [u8]) -> PrintFuture {
     kernel_set_print_callback(callback);
     kernel_start_print(buffer);
@@ -76,7 +76,7 @@ extern fn callback() {
 
 So far so good. Barbara then works on `poll`:
 
-```rust
+```rust,ignore
     fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
         if kernel_is_print_done() {
             return Poll::Ready(kernel_get_buffer_back());
@@ -92,7 +92,7 @@ somewhere! Barbara puts the `Waker` in a global variable so the callback can
 find it (this is fine because the app is single threaded and callbacks do NOT
 interrupt execution the way Unix signals do):
 
-```rust
+```rust,ignore
 static mut PRINT_WAKER: Option<Waker> = None;
 
 extern fn callback() {
@@ -104,7 +104,7 @@ extern fn callback() {
 
 She then modifies `poll` to set `PRINT_WAKER`:
 
-```rust
+```rust,ignore
     fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
         if kernel_is_print_done() {
             return Poll::Ready(kernel_get_buffer_back());

src/vision/status_quo/barbara_plays_with_async.md

@@ -43,7 +43,7 @@ that will wait for a certain duration to elapse before resolving.
 Borrowing again from the "Hello Tokio" tutorial to make sure she has the correct
 spelling for the tokio macros, she writes up the following code:
 
-```rust
+```rust,ignore
 #[tokio::main]
 pub async fn main() {
     let mut rng = thread_rng();
@@ -72,7 +72,7 @@ seconds doing nothing, and giving no hints about what it's actually doing.
 So for the next iteration, Barbara wants to have a message printed out
 when each future is resolved.  She tries this code at first:
 
-```rust
+```rust,ignore
 let mut futures = Vec::new();
 for _ in 0..10 {
     let delay = rng.sample(t);
@@ -85,7 +85,7 @@ println!("Created 10 futures");
 
 But the compiler gives this error:
 
-```
+```ignore
 error[E0277]: `()` is not a future
   --> src\main.rs:13:71
    |
@@ -105,7 +105,7 @@ which looks interesting.
 Indeed, this struct is a future that will resolve instantly, which is what
 she wants:
 
-```rust
+```rust,ignore
 for _ in 0..10 {
     let delay = rng.sample(t);
     futures.push(tokio::time::sleep(Duration::from_millis(delay)).then(|_| {
@@ -129,7 +129,7 @@ always printed all at once.
 Barbara has experience writing async code in JavaScript, and so she thinks for
 a moment about how this toy code might have looked like if she was using JS:
 
-```javascript
+```javascript,ignore
 async function main() {
     const futures = [];
     for (let idx = 0; idx < 10; idx++) {
@@ -161,7 +161,7 @@ and remembers that there's a 3rd-party crate called "[futures][futures crate]"
 on crates.io that she's seen mentioned in some /r/rust posts.  She checks the
 docs and finds the `join_all` function which looks like what she wants:
 
-```rust
+```rust,ignore
 let mut futures = Vec::new();
 for _ in 0..10 {
     let delay = rng.sample(t);
@@ -182,7 +182,7 @@ rust futures are lazy, and won't make progress unless you await them.
 Happy with this success, Barbara continues to expand her toy program by making
 a few small adjustments:
 
-```rust
+```rust,ignore
 for counter in 0..10 {
     let delay = rng.sample(t);
     let delay_future = tokio::time::sleep(Duration::from_millis(delay));
@@ -203,7 +203,7 @@ for counter in 0..10 {
 
 This fails to compile:
 
-```
+```ignore
 error[E0308]: mismatched types
 
    = note: expected closure `[closure@src\main.rs:16:44: 19:14]`
@@ -220,7 +220,7 @@ entire future.
 
 She first adds explicit type annotations to the Vec:
 
-```rust
+```rust,ignore
 let mut futures: Vec<Box<dyn Future<Output=()>>> = Vec::new();
 ```
 
@@ -232,7 +232,7 @@ rust-analyzer perfectly handled this case.
 Now each future is boxed up, but there is one final error still,
 this time on the call to `join_all(futures).await`:
 
-```
+```ignore
 error[E0277]: `dyn futures::Future<Output = ()>` cannot be unpinned
   --> src\main.rs:34:31
    |
@@ -245,7 +245,7 @@ intuition about what this API is for.  But she is accustomed to just trying
 things in rust to see if they work.  And indeed, after changing `Box::new` to
 `Box::pin`:
 
-```rust
+```rust,ignore
 futures.push(Box::pin(delay_future.then(|_| {
     println!("Done!");
     std::future::ready(())
@@ -254,7 +254,7 @@ futures.push(Box::pin(delay_future.then(|_| {
 
 and adjusting the type of the Vec:
 
-```rust
+```rust,ignore
 let mut futures: Vec<Pin<Box<dyn Future<Output=()>>>> = Vec::new();
 ```
 
@@ -272,7 +272,7 @@ post about async rust a few weeks ago, and has a vague idea of how it looks.
 
 She tries writing this:
 
-```rust
+```rust,ignore
 futures.push(Box::pin(async || {
     tokio::time::sleep(Duration::from_millis(delay)).await;
     println!("Done after {}ms", delay);
@@ -281,7 +281,7 @@ futures.push(Box::pin(async || {
 
 The compiler gives an error:
 
-```
+```ignore
 error[E0658]: async closures are unstable
   --> src\main.rs:14:31
    |
@@ -296,7 +296,7 @@ error[E0658]: async closures are unstable
 Barbara knows that async is stable and using this nightly feature isn't what
 she wants.  So the tries the suggestion made by the compiler and removes the `||` bars:
 
-```rust
+```rust,ignore
 futures.push(Box::pin(async {
     tokio::time::sleep(Duration::from_millis(delay)).await;
     println!("Done after {}ms", delay);
@@ -305,7 +305,7 @@ futures.push(Box::pin(async {
 
 A new error this time:
 
-```
+```ignore
 error[E0597]: `delay` does not live long enough
 15 | |             tokio::time::sleep(Duration::from_millis(delay)).await;
    | |                                                      ^^^^^ borrowed value does not live long enough
@@ -318,7 +318,7 @@ to an async block), but Barbara's experience with rust tells her that it's a ver
 consistent language.  Maybe the same keyword used in move closures will work here?
 She tries it:
 
-```rust
+```rust,ignore
 futures.push(Box::pin(async move {
     tokio::time::sleep(Duration::from_millis(delay)).await;
     println!("Done after {}ms", delay);

src/vision/status_quo/barbara_trims_a_stacktrace.md

@@ -18,7 +18,7 @@ If you would like to expand on this story, or adjust the answers to the FAQ, fee
 
 Barbara is triaging the reported bugs for her SLOW library. For each bug, she tries to quickly see if she can diagnose the basic area of code that is affected so she knows which people to ping to help fix it. She opens a bug report from a user complaining about a panic when too many connections arrive at the same time. The bug report includes a backtrace from the user's code, and it looks like this:
 
-```
+```ignore
 thread 'main' panicked at 'something bad happened here', src/main.rs:16:5
 stack backtrace:
    0: std::panicking::begin_panic
@@ -74,7 +74,7 @@ Barbara finds the text overwhelming. She can't just browse it to figure out what
 
 She's a bit confused by the `::{closure}` lines on her symbols but she learned by now that this is normal for `async fn`. After some work, she has reduced her stack to this:
 
-```
+```ignore
 thread 'main' panicked at 'something bad happened here', src/main.rs:16:5
 stack backtrace:
    1: slow_rs::process_one::{{closure}} at ./src/main.rs:16:5
@@ -117,7 +117,7 @@ Fin.
 <details>
 <summary>(click to see how a backtrace looks in lldb)</summary>
 
-```
+```ignore
 * thread #1, name = 'foo', stop reason = breakpoint 1.1
   * frame #0: 0x0000555555583d24 foo`foo::main::_$u7b$$u7b$closure$u7d$$u7d$::_$u7b$$u7b$closure$u7d$$u7d$::h617d49d0841ffc0d((null)=closure-0 @ 0x00007fffffffae38, (null)=<unavailable>) at main.rs:11:13
     frame #1: 0x0000555555583d09 foo`_$LT$T$u20$as$u20$futures_util..fns..FnOnce1$LT$A$GT$$GT$::call_once::hc559b1f3f708a7b0(self=closure-0 @ 0x00007fffffffae68, arg=<unavailable>) at fns.rs:15:9