Merge branch 'master' into book-typos-and-small-edits

Author: skade

docs/src/concepts/futures.md

@@ -99,7 +99,7 @@ Every call to `poll()` can result in one of these two cases:
 2. The computation has not finished executing, it will return [`Poll::Pending`](https://doc.rust-lang.org/std/task/enum.Poll.html#variant.Pending)
 
 This allows us to externally check if a `Future` still has unfinished work, or is finally done and can give us the value. The most simple (but not efficient) way would be to just constantly poll futures in a loop. There are optimisations possible, and this is what a good runtime does for you.
-Note that calling `poll` after case 1 happened may result in confusing behaviour. See the [futures-docs](https://doc.rust-lang.org/std/future/trait.Future.html) for details.
+Note that calling `poll` again after case 1 happened may result in confusing behaviour. See the [futures-docs](https://doc.rust-lang.org/std/future/trait.Future.html) for details.
 
 ## Async
 
@@ -118,7 +118,7 @@ async fn read_file(path: &str) -> Result<String, io::Error> {
 
 Amazingly little difference, right? All we did is label the function `async` and insert 2 special commands: `.await`.
 
-This `async` function sets up a deferred computation. When this function is called, instead of returning the computed `String`, it will produce a `Future<Output=String>`. (Or, more precisely, will generate a type for you that implements `Future<Output=String>`.)
+This `async` function sets up a deferred computation. When this function is called, it will produce a `Future<Output=Result<String, io::Error>>` instead of immediately returning a `Result<String, io::Error>`. (Or, more precisely, generate a type for you that implements `Future<Output=Result<String, io::Error>>`.)
 
 ## What does `.await` do?
 
@@ -137,3 +137,5 @@ A `Future` is any data type that does not represent a value, but the ability to
 Next, we will introduce you to `tasks`, which we need to actually *run* Futures.
 
 [^1]: Two parties reading while it is guaranteed that no one is writing is always safe.
+
+[futures]: https://rust-lang.github.io/async-book/02_execution/02_future.html

docs/src/concepts/tasks.md

@@ -17,7 +17,7 @@ async fn read_file(path: &str) -> Result<String, io::Error> {
 
 fn main() {
     let reader_task = task::spawn(async {
-        let result = read_file("data.csv");
+        let result = read_file("data.csv").await;
         match result {
             Ok(s) => println!("{}", s),
             Err(e) => println!("Error reading file: {:?}", e)
@@ -33,7 +33,7 @@ This asks the runtime baked into `async_std` to execute the code that reads a fi
 
 ```rust
 async {
-    let result = read_file("data.csv");
+    let result = read_file("data.csv").await;
     match result {
         Ok(s) => println!("{}", s),
         Err(e) => println!("Error reading file: {:?}", e)

docs/src/glossary.md

@@ -2,6 +2,6 @@
 
 ### blocking
 
-"blocked" generally refers to conditions that keep a task from doing its work. For example, it might need data to be sent by a client before continuing. When tasks becomes blocked, usually, other tasks are scheduled.
+"blocked" generally refers to conditions that keep a task from doing its work. For example, it might need data to be sent by a client before continuing. When tasks become blocked, usually, other tasks are scheduled.
 
-Sometimes you hear that you should never call "blocking functions" in an async context. What this refers to is functions that block the current thread and do not yield control back. This keeps the executor from using this thread to schedule another task.
+Sometimes you hear that you should never call "blocking functions" in an async context. What this refers to is functions that block the current thread and do not yield control back. This keeps the executor from using this thread to schedule another task.

docs/src/introduction.md

@@ -2,7 +2,7 @@
 
 ![async-std logo](./images/horizontal_color.svg)
 
-This book serves as high-level documentation for `async-std` and a way of learning async programming in Rust through it. As such, it focusses on the `async-std` API and the task model it gives you.
+This book serves as high-level documentation for `async-std` and a way of learning async programming in Rust through it. As such, it focuses on the `async-std` API and the task model it gives you.
 
 Please note that the Rust project provides its own book on asynchronous programming, called ["Asynchronous Programming in Rust"][async-book], which we highly recommend reading along with this book, as it provides a different, wider view on the topic.
 

docs/src/overview/async-std.md

@@ -1,8 +1,8 @@
 # Welcome to `async-std`
 
-`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`, along with its [supporting libraries][organization], is a library making your life in async programming easier. It provides fundamental implementations for downstream libraries and applications alike. The name reflects the approach of this library: it is as 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].
+`async-std` provides an interface to all important primitives: filesystem operations, network operations and concurrency basics like timers. It also exposes a `task` in a model similar to the `thread` module found in the Rust standard lib.  But it does not only include I/O 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-rs/async-std
 [overview-std]: overview/async-std/

docs/src/overview/stability-guarantees.md

@@ -35,6 +35,6 @@ Security fixes will be applied to _all_ minor branches of this library in all _s
 
 ## Credits
 
-This policy is based on [burntsushis regex crate][regex-policy].
+This policy is based on [BurntSushi's regex crate][regex-policy].
 
 [regex-policy]: https://github.com/rust-lang/regex#minimum-rust-version-policy

docs/src/overview/std-and-library-futures.md

@@ -10,13 +10,13 @@ The future defined in the [futures-rs](https://docs.rs/futures-preview/0.3.0-alp
 
 It is critical to understand the difference between `std::future::Future` and `futures::future::Future`, and the approach that `async-std` takes towards them. In itself, `std::future::Future` is not something you want to interact with as a user—except by calling `.await` on it. The inner workings of `std::future::Future` are mostly of interest to people implementing `Future`. Make no mistake—this is very useful! Most of the functionality that used to be defined on `Future` itself has been moved to an extension trait called [`FuturesExt`](https://docs.rs/futures-preview/0.3.0-alpha.17/futures/future/trait.FutureExt.html). From this information, you might be able to infer that the `futures` library serves as an extension to the core Rust async features.
 
-In the same tradition as `futures`, `async-std` re-exports the core `std::future::Future` type. You can get actively opt into the extensions provided by the `futures-preview` crate by adding it your `Cargo.toml` and importing `FuturesExt`.
+In the same tradition as `futures`, `async-std` re-exports the core `std::future::Future` type. You can actively opt into the extensions provided by the `futures-preview` crate by adding it to your `Cargo.toml` and importing `FuturesExt`.
 
 ## Interfaces and Stability
 
  `async-std` aims to be a stable and reliable library, at the level of the Rust standard library. This also means that we don't rely on the `futures` library for our interface. Yet, we appreciate that many users have come to like the conveniences that `futures-rs` brings. For that reason, `async-std` implements all `futures` traits for its types.
 
- Luckily, the approach from above gives you full flexibility. If you care about stability a lot, you can just use `async-std` as is. If you prefer the `futures` library interfaces, you link those in.. Both uses are first class.
+ Luckily, the approach from above gives you full flexibility. If you care about stability a lot, you can just use `async-std` as is. If you prefer the `futures` library interfaces, you link those in. Both uses are first class.
 
 ## `async_std::future`
 

docs/src/tutorial/accept_loop.md

@@ -21,8 +21,8 @@ type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>
 
 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.
+2. `prelude` re-exports some traits required to work with futures and streams.
+3. The `task` module roughly corresponds to the `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.
@@ -43,7 +43,7 @@ async fn server(addr: impl ToSocketAddrs) -> Result<()> { // 1
 }
 ```
 
-1. We mark `server` function as `async`, which allows us to use `.await` syntax inside.
+1. We mark the `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.
@@ -73,4 +73,4 @@ The crucial thing to realise that is in Rust, unlike other languages, calling an
 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.
+In this case, we use `task::block_on` to execute a future on the current thread and block until it's done.

docs/src/tutorial/all_together.md

@@ -1,7 +1,7 @@
 
 ## All Together
 
-At this point, we only need to start broker to get a fully-functioning (in the happy case!) chat:
+At this point, we only need to start the broker to get a fully-functioning (in the happy case!) chat:
 
 ```rust
 #![feature(async_await)]
@@ -129,7 +129,7 @@ async fn broker(mut events: Receiver<Event>) -> Result<()> {
 }
 ```
 
-1. Inside the `server`, we create broker's channel and `task`.
+1. Inside the `server`, we create the 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.

docs/src/tutorial/clean_shutdown.md

@@ -1,6 +1,6 @@
 ## Clean Shutdown
 
-On of the problems of the current implementation is that it doesn't handle graceful shutdown.
+One 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:
 
@@ -10,7 +10,7 @@ A more correct shutdown sequence would be:
 
 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.
+That is, as soon as producers exit and drop their senders, the rest of the system shuts down naturally.
 In `async_std` this translates to two rules:
 
 1. Make sure that channels form an acyclic graph.
@@ -83,4 +83,4 @@ Notice what happens with all of the channels once we exit the accept 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.
+5. Finally, we join the broker, which also guarantees that all the writes have terminated.