Seperate the tutorial in multiple parts

Fix some typos

Author: skade

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/async-rs/async-std.svg?branch=master)](https://travis-ci.org/stjepang/async-std)
 [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](
-https://github.com/async-std/async-std)
+https://github.com/async-rs/async-std)
 [![Cargo](https://img.shields.io/crates/v/async-std.svg)](https://crates.io/crates/async-std)
 [![Documentation](https://docs.rs/async-std/badge.svg)](https://docs.rs/async-std)
 [![chat](https://img.shields.io/discord/598880689856970762.svg?logo=discord)](https://discord.gg/JvZeVNe)

docs/src/SUMMARY.md

@@ -1,6 +1,6 @@
 # Summary
 
-- [Overview](./overview.md)
+- [Welcome to `async-std`!](./overview.md)
   - [`async-std`](./overview/async-std.md)
   - [`std::future` and `futures-rs`](./overview/std-and-library-futures.md)
   - [Stability guarantees](./overview/stability-guarantees.md)
@@ -9,16 +9,18 @@
   - [Tasks](./concepts/tasks.md)
   - [Async read/write](./concepts/async-read-write.md)
   - [Streams and Channels](./concepts/streams.md)
-- [Tutorials](./tutorials/index.md)
-  - [Integrating std::thread](./tutorials/integrating-std-thread.md)
-  - [Implementing a Chat Server](./tutorials/chat.md)
-- [Async Patterns](./patterns.md)
-  - [Fork/Join](./patterns/fork-join.md)
-  - [Accepting requests](./patterns/accepting-concurrent-requests.md)
-  - [Proper Shutdown](./patterns/proper-shutdown.md)
-  - [Background Tasks](./patterns/background-tasks.md)
-  - [Testing](./patterns/testing.md)
-  - [Collected Small Patterns](./patterns/small-patterns.md)
+- [Tutorial: Implementing a chat](./tutorial/index.md)
+  - [Specification and Getting started](./tutorial/specification.md)
+  - [Writing an Accept Loop](./tutorial/accept_loop.md)
+  - [Receiving Messages](./tutorial/receiving_messages.md)
+  - [Sending Messages](./tutorial/sending_messages.md)
+  - [Connecting Readers and Writers](./tutorial/connecting_readers_and_writers.md)
+  - [All Together](./tutorial/all_together.md)
+  - [Clean Shutdown](./tutorial/clean_shutdown.md)
+  - [Handling Disconnections](./tutorial/handling_disconnections.md)
+  - [Implementing a Client](./tutorial/implementing_a_client.md)
+- [TODO: Async Patterns](./patterns.md)
+  - [TODO: Collected Small Patterns](./patterns/small-patterns.md)
 - [Security practices](./security/index.md)
-  - [Security disclosures and policy](./security/policy.md)
+  - [Security Disclosures and Policy](./security/policy.md)
 - [Glossary](./glossary.md)

docs/src/overview.md

@@ -1,10 +1,10 @@
-# Overview
+# Welcome to `async-std`
 
 ![async-std logo](./images/horizontal_color.svg)
 
 `async-std` along with its [supporting libraries][organization] is a library making your life in async programming easier. It provides provide fundamental implementations for downstream libraries and applications alike. The name reflects the approach of this library: it is a closely modeled to the Rust main standard library as possible, replacing all components by async counterparts.
 
 `async-std` provides an interface to all important primitives: filesystem operations, network operations and concurrency basics like timers. It also exposes an `task` in a model similar to the `thread` module found in the Rust standard lib.  But it does not only include io primitives, but also `async/await` compatible versions of primitives like `Mutex`. You can read more about `async-std` in [the overview chapter][overview-std].
 
-[organization]: https://github.com/async-std/async-std
+[organization]: https://github.com/async-rs/async-std
 [overview-std]: overview/async-std/

docs/src/security/index.md

@@ -8,5 +8,5 @@ In the case that you find a security-related bug in our library, please get in t
 
 Patches improving the resilience of the library or the testing setup are happily accepted on our [github org][github].
 
-[security-policies]: /security/policy
-[github]: https://github.com/async-std/
+[security-policy]: /security/policy
+[github]: https://github.com/async-rs

docs/src/tutorial/accept_loop.md

@@ -0,0 +1,76 @@
+## Writing an Accept Loop
+
+Let's implement the scaffold of the server: a loop that binds a TCP socket to an address and starts accepting connections.
+
+
+First of all, let's add required import boilerplate:
+
+```rust
+#![feature(async_await)]
+
+use std::net::ToSocketAddrs; // 1
+
+use async_std::{
+    prelude::*, // 2
+    task,       // 3
+    net::TcpListener, // 4
+};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>; // 5
+```
+
+1. `async_std` uses `std` types where appropriate.
+    We'll need `ToSocketAddrs` to specify address to listen on.
+2. `prelude` re-exports some traits required to work with futures and streams
+3. The `task` module roughtly corresponds to `std::thread` module, but tasks are much lighter weight.
+   A single thread can run many tasks.
+4. For the socket type, we use `TcpListener` from `async_std`, which is just like `std::net::TcpListener`, but is non-blocking and uses `async` API.
+5. We will skip implementing comprehensive error handling in this example.
+   To propagate the errors, we will use a boxed error trait object.
+   Do you know that there's `From<&'_ str> for Box<dyn Error>` implementation in stdlib, which allows you to use strings with `?` operator?
+
+
+Now we can write the server's accept loop:
+
+```rust
+async fn server(addr: impl ToSocketAddrs) -> Result<()> { // 1
+    let listener = TcpListener::bind(addr).await?; // 2
+    let mut incoming = listener.incoming();
+    while let Some(stream) = incoming.next().await { // 3
+        // TODO
+    }
+    Ok(())
+}
+```
+
+1. We mark `server` function as `async`, which allows us to use `.await` syntax inside.
+2. `TcpListener::bind` call returns a future, which we `.await` to extract the `Result`, and then `?` to get a `TcpListener`.
+   Note how `.await` and `?` work nicely together.
+   This is exactly how `std::net::TcpListener` works, but with `.await` added.
+   Mirroring API of `std` is an explicit design goal of `async_std`.
+3. Here, we would like to iterate incoming sockets, just how one would do in `std`:
+
+   ```rust
+   let listener: std::net::TcpListener = unimplemented!();
+   for stream in listener.incoming() {
+
+   }
+   ```
+
+   Unfortunately this doesn't quite work with `async` yet, because there's no support for `async` for-loops in the language yet.
+   For this reason we have to implement the loop manually, by using `while let Some(item) = iter.next().await` pattern.
+
+Finally, let's add main:
+
+```rust
+fn main() -> Result<()> {
+    let fut = server("127.0.0.1:8080");
+    task::block_on(fut)
+}
+```
+
+The crucial thing to realise that is in Rust, unlike other languages, calling an async function does **not** run any code.
+Async functions only construct futures, which are inert state machines.
+To start stepping through the future state-machine in an async function, you should use `.await`.
+In a non-async function, a way to execute a future is to handle it to the executor.
+In this case, we use `task::block_on` to execute future on the current thread and block until it's done.

docs/src/tutorial/all_together.md

@@ -0,0 +1,136 @@
+
+## All Together
+
+At this point, we only need to start broker to get a fully-functioning (in the happy case!) chat:
+
+```rust
+#![feature(async_await)]
+
+use std::{
+    net::ToSocketAddrs,
+    sync::Arc,
+    collections::hash_map::{HashMap, Entry},
+};
+
+use futures::{
+    channel::mpsc,
+    SinkExt,
+};
+
+use async_std::{
+    io::BufReader,
+    prelude::*,
+    task,
+    net::{TcpListener, TcpStream},
+};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
+type Sender<T> = mpsc::UnboundedSender<T>;
+type Receiver<T> = mpsc::UnboundedReceiver<T>;
+
+
+fn main() -> Result<()> {
+    task::block_on(server("127.0.0.1:8080"))
+}
+
+async fn server(addr: impl ToSocketAddrs) -> Result<()> {
+    let listener = TcpListener::bind(addr).await?;
+
+    let (broker_sender, broker_receiver) = mpsc::unbounded(); // 1
+    let _broker_handle = task::spawn(broker(broker_receiver));
+    let mut incoming = listener.incoming();
+    while let Some(stream) = incoming.next().await {
+        let stream = stream?;
+        println!("Accepting from: {}", stream.peer_addr()?);
+        spawn_and_log_error(client(broker_sender.clone(), stream));
+    }
+    Ok(())
+}
+
+async fn client(mut broker: Sender<Event>, stream: TcpStream) -> Result<()> {
+    let stream = Arc::new(stream); // 2
+    let reader = BufReader::new(&*stream);
+    let mut lines = reader.lines();
+
+    let name = match lines.next().await {
+        None => Err("peer disconnected immediately")?,
+        Some(line) => line?,
+    };
+    broker.send(Event::NewPeer { name: name.clone(), stream: Arc::clone(&stream) }).await // 3
+        .unwrap();
+
+    while let Some(line) = lines.next().await {
+        let line = line?;
+        let (dest, msg) = match line.find(':') {
+            None => continue,
+            Some(idx) => (&line[..idx], line[idx + 1 ..].trim()),
+        };
+        let dest: Vec<String> = dest.split(',').map(|name| name.trim().to_string()).collect();
+        let msg: String = msg.trim().to_string();
+
+        broker.send(Event::Message { // 4
+            from: name.clone(),
+            to: dest,
+            msg,
+        }).await.unwrap();
+    }
+    Ok(())
+}
+
+async fn client_writer(
+    mut messages: Receiver<String>,
+    stream: Arc<TcpStream>,
+) -> Result<()> {
+    let mut stream = &*stream;
+    while let Some(msg) = messages.next().await {
+        stream.write_all(msg.as_bytes()).await?;
+    }
+    Ok(())
+}
+
+#[derive(Debug)]
+enum Event {
+    NewPeer {
+        name: String,
+        stream: Arc<TcpStream>,
+    },
+    Message {
+        from: String,
+        to: Vec<String>,
+        msg: String,
+    },
+}
+
+async fn broker(mut events: Receiver<Event>) -> Result<()> {
+    let mut peers: HashMap<String, Sender<String>> = HashMap::new();
+
+    while let Some(event) = events.next().await {
+        match event {
+            Event::Message { from, to, msg } => {
+                for addr in to {
+                    if let Some(peer) = peers.get_mut(&addr) {
+                        peer.send(format!("from {}: {}\n", from, msg)).await?
+                    }
+                }
+            }
+            Event::NewPeer { name, stream} => {
+                match peers.entry(name) {
+                    Entry::Occupied(..) => (),
+                    Entry::Vacant(entry) => {
+                        let (client_sender, client_receiver) = mpsc::unbounded();
+                        entry.insert(client_sender); // 4
+                        spawn_and_log_error(client_writer(client_receiver, stream)); // 5
+                    }
+                }
+            }
+        }
+    }
+    Ok(())
+}
+```
+
+1. Inside the `server`, we create broker's channel and `task`.
+2. Inside `client`, we need to wrap `TcpStream` into an `Arc`, to be able to share it with the `client_writer`.
+3. On login, we notify the broker.
+   Note that we `.unwrap` on send: broker should outlive all the clients and if that's not the case the broker probably panicked, so we can escalate the panic as well.
+4. Similarly, we forward parsed messages to the broker, assuming that it is alive.

docs/src/tutorial/clean_shutdown.md

@@ -0,0 +1,86 @@
+## Clean Shutdown
+
+On of the problems of the current implementation is that it doesn't handle graceful shutdown.
+If we break from the accept loop for some reason, all in-flight tasks are just dropped on the floor.
+A more correct shutdown sequence would be:
+
+1. Stop accepting new clients
+2. Deliver all pending messages
+3. Exit the process
+
+A clean shutdown in a channel based architecture is easy, although it can appear a magic trick at first.
+In Rust, receiver side of a channel is closed as soon as all senders are dropped.
+That is, as soon as producers exit and drop their senders, the rest of the system shutdowns naturally.
+In `async_std` this translates to two rules:
+
+1. Make sure that channels form an acyclic graph.
+2. Take care to wait, in the correct order, until intermediate layers of the system process pending messages.
+
+In `a-chat`, we already have an unidirectional flow of messages: `reader -> broker -> writer`.
+However, we never wait for broker and writers, which might cause some messages to get dropped.
+Let's add waiting to the server:
+
+```rust
+async fn server(addr: impl ToSocketAddrs) -> Result<()> {
+    let listener = TcpListener::bind(addr).await?;
+
+    let (broker_sender, broker_receiver) = mpsc::unbounded();
+    let broker = task::spawn(broker(broker_receiver));
+    let mut incoming = listener.incoming();
+    while let Some(stream) = incoming.next().await {
+        let stream = stream?;
+        println!("Accepting from: {}", stream.peer_addr()?);
+        spawn_and_log_error(client(broker_sender.clone(), stream));
+    }
+    drop(broker_sender); // 1
+    broker.await?; // 5
+    Ok(())
+}
+```
+
+And to the broker:
+
+```rust
+async fn broker(mut events: Receiver<Event>) -> Result<()> {
+    let mut writers = Vec::new();
+    let mut peers: HashMap<String, Sender<String>> = HashMap::new();
+
+    while let Some(event) = events.next().await { // 2
+        match event {
+            Event::Message { from, to, msg } => {
+                for addr in to {
+                    if let Some(peer) = peers.get_mut(&addr) {
+                        peer.send(format!("from {}: {}\n", from, msg)).await?
+                    }
+                }
+            }
+            Event::NewPeer { name, stream} => {
+                match peers.entry(name) {
+                    Entry::Occupied(..) => (),
+                    Entry::Vacant(entry) => {
+                        let (client_sender, client_receiver) = mpsc::unbounded();
+                        entry.insert(client_sender);
+                        let handle = spawn_and_log_error(client_writer(client_receiver, stream));
+                        writers.push(handle); // 4
+                    }
+                }
+            }
+        }
+    }
+    drop(peers); // 3
+    for writer in writers { // 4
+        writer.await?;
+    }
+    Ok(())
+}
+```
+
+Notice what happens with all of the channels once we exit the accept loop:
+
+1. First, we drop the main broker's sender.
+   That way when the readers are done, there's no sender for the broker's channel, and the chanel closes.
+2. Next, the broker exits `while let Some(event) = events.next().await` loop.
+3. It's crucial that, at this stage, we drop the `peers` map.
+   This drops writer's senders.
+4. Now we can join all of the writers.
+5. Finally, we join the broker, which also guarantees that all the writes have terminated.