Skip to content

Commit e43c006

Browse files
authored
Merge branch 'master' into book-typos-and-small-edits
2 parents 2d2490c + 2921570 commit e43c006

File tree

4 files changed

+14
-10
lines changed

4 files changed

+14
-10
lines changed

docs/src/concepts/futures.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Note how we avoided any word like *"thread"*, but instead opted for "computation
1818

1919
To sum up: Rust gives us the ability to safely abstract over important properties of concurrent programs, their data sharing. It does so in a very lightweight fashion; the language itself only knows about the two markers `Send` and `Sync` and helps us a little by deriving them itself, when possible. The rest is a library concern.
2020

21+
[rust-book-sync]: https://doc.rust-lang.org/stable/book/ch16-04-extensible-concurrency-sync-and-send.html
22+
2123
## An easy view of computation
2224

2325
While computation is a subject to write a whole [book](https://computationbook.com/) about, a very simplified view suffices for us:
@@ -28,7 +30,7 @@ While computation is a subject to write a whole [book](https://computationbook.c
2830

2931
## Deferring computation
3032

31-
As mentioned above `Send` and `Sync` are about data. But programs are not only about data, they also talk about *computing* the data. And that's what \[Futures\][futures] do. We are going to have a close look at how that works in the next chapter. Let's look at what Futures allow us to express, in English. Futures go from this plan:
33+
As mentioned above `Send` and `Sync` are about data. But programs are not only about data, they also talk about *computing* the data. And that's what [`Futures`][futures] do. We are going to have a close look at how that works in the next chapter. Let's look at what Futures allow us to express, in English. Futures go from this plan:
3234

3335
- Do X
3436
- If X succeeds, do Y
@@ -40,6 +42,8 @@ towards
4042

4143
Remember the talk about "deferred computation" in the intro? That's all it is. Instead of telling the computer what to execute and decide upon *now*, you tell it what to start doing and how to react on potential events the... well... `Future`.
4244

45+
[futures]: https://doc.rust-lang.org/std/future/trait.Future.html
46+
4347
## Orienting towards the beginning
4448

4549
Let's have a look at a simple function, specifically the return value:
@@ -77,8 +81,8 @@ What we are searching is something that represents ongoing work towards a result
7781
Ignore `Pin` and `Context` for now, you don't need them for high-level understanding. Looking at it closely, we see the following: it is generic over the `Output`. It provides a function called `poll`, which allows us to check on the state of the current computation.
7882
Every call to `poll()` can result in one of these two cases:
7983

80-
1. The future is done, `poll` will return `[Poll::Ready](https://doc.rust-lang.org/std/task/enum.Poll.html#variant.Ready)`
81-
2. The future has not finished executing, it will return `[Poll::Pending](https://doc.rust-lang.org/std/task/enum.Poll.html#variant.Pending)`
84+
1. The future is done, `poll` will return [`Poll::Ready`](https://doc.rust-lang.org/std/task/enum.Poll.html#variant.Ready)
85+
2. The future has not finished executing, it will return [`Poll::Pending`](https://doc.rust-lang.org/std/task/enum.Poll.html#variant.Pending)
8286

8387
This allows us to externally check if a `Future` has finished doing its work, or is finally done and can give us the value. The most simple way (but not efficient) would be to just constantly poll futures in a loop. There's optimisations here, and this is what a good runtime is does for you.
8488
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.

docs/src/concepts/tasks.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,15 @@ async fn read_file(path: &str) -> Result<String, io::Error> {
1616
}
1717

1818
fn main() {
19-
let task = task::spawn(async {
19+
let reader_task = task::spawn(async {
2020
let result = read_file("data.csv");
2121
match result {
2222
Ok(s) => println!("{}", s),
2323
Err(e) => println!("Error reading file: {:?}", e)
2424
}
2525
});
2626
println!("Started task!");
27-
task::block_on(task);
27+
task::block_on(reader_task);
2828
println!("Stopped task!");
2929
}
3030
```

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ Rust has two kinds of types commonly referred to as `Future`:
66
- the first is `std::future::Future` from Rust’s [standard library](https://doc.rust-lang.org/std/future/trait.Future.html).
77
- the second is `futures::future::Future` from the [futures-rs crate](https://docs.rs/futures-preview/0.3.0-alpha.17/futures/prelude/trait.Future.html), currently released as `futures-preview`.
88

9-
The future defined in the [futures-rs](https://docs.rs/futures-preview/0.3.0-alpha.17/futures/prelude/trait.Future.html) crate was the original implementation of the type. To enable the `async/await` syntax, the core Future trait was moved into Rust’s standard library and became `std::future::Future`. In some sense, the `std``::future::Future` can be seen as a minimal subset of `futures::future::Future`.
9+
The future defined in the [futures-rs](https://docs.rs/futures-preview/0.3.0-alpha.17/futures/prelude/trait.Future.html) crate was the original implementation of the type. To enable the `async/await` syntax, the core Future trait was moved into Rust’s standard library and became `std::future::Future`. In some sense, the `std::future::Future` can be seen as a minimal subset of `futures::future::Future`.
1010

11-
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.
11+
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.
1212

13-
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`.
13+
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`.
1414

1515
## Interfaces and Stability
1616

@@ -24,4 +24,4 @@ There’s some support functions that we see as important for working with futur
2424

2525
## Streams and Read/Write/Seek/BufRead traits
2626

27-
Due to limitations of the Rust compiler, those are currently implemented in `async_std`, but cannot be implemented by users themselves.
27+
Due to limitations of the Rust compiler, those are currently implemented in `async_std`, but cannot be implemented by users themselves.

docs/src/tutorial/receiving_messages.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,4 +89,4 @@ where
8989
}
9090
})
9191
}
92-
```s
92+
```

0 commit comments

Comments
 (0)