public-collect/books-futures-explained
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Put plural endings after grave accents

Browse Source
This commit is contained in:
olehmisar
2020-04-08 13:53:35 +03:00
parent a3ac3071df
commit 8dfc2f8ed3
7 changed files with 175 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/0_background_information.md
View File

@@ -102,7 +102,7 @@ such a system) which then continues running a different task.
Rust had green threads once, but they were removed before it hit 1.0. The state Rust had green threads once, but they were removed before it hit 1.0. The state
of execution is stored in each stack so in such a solution there would be no of execution is stored in each stack so in such a solution there would be no
need for `async`, `await`, `Futures` or `Pin`. need for `async`, `await`, `Future`s or `Pin`.
**The typical flow looks like this:** **The typical flow looks like this:**
@@ -482,11 +482,11 @@ as timers but could represent any kind of resource that we'll have to wait for.
You might start to wonder by now, when are we going to talk about Futures? You might start to wonder by now, when are we going to talk about Futures?
Well, we're getting there. You see `promises`, `futures` and other names for Well, we're getting there. You see `Promise`s, `Future`s and other names for
deferred computations are often used interchangeably. deferred computations are often used interchangeably.
There are formal differences between them but we'll not cover that here but it's There are formal differences between them but we'll not cover that here but it's
worth explaining `promises` a bit since they're widely known due to being used worth explaining `Promise`s a bit since they're widely known due to being used
in Javascript and have a lot in common with Rusts Futures. in Javascript and have a lot in common with Rusts Futures.
First of all, many languages has a concept of promises but I'll use the ones First of all, many languages has a concept of promises but I'll use the ones

6
src/1_futures_in_rust.md
View File

@@ -91,7 +91,7 @@ Rust is different from these languages in the sense that Rust doesn't come with
a runtime for handling concurrency, so you need to use a library which provide a runtime for handling concurrency, so you need to use a library which provide
this for you. this for you.
Quite a bit of complexity attributed to `Futures` is actually complexity rooted Quite a bit of complexity attributed to `Future`s is actually complexity rooted
in runtimes. Creating an efficient runtime is hard. in runtimes. Creating an efficient runtime is hard.
Learning how to use one correctly requires quite a bit of effort as well, but Learning how to use one correctly requires quite a bit of effort as well, but
@@ -114,7 +114,7 @@ on the `Future`.
You can think of the former as the reactor's job, and the latter as the You can think of the former as the reactor's job, and the latter as the
executors job. These two parts of a runtime interacts using the `Waker` type. executors job. These two parts of a runtime interacts using the `Waker` type.
The two most popular runtimes for `Futures` as of writing this is: The two most popular runtimes for `Future`s as of writing this is:
- [async-std](https://github.com/async-rs/async-std) - [async-std](https://github.com/async-rs/async-std)
- [Tokio](https://github.com/tokio-rs/tokio) - [Tokio](https://github.com/tokio-rs/tokio)
@@ -198,7 +198,7 @@ Take a break or a cup of coffe and get ready as we go for a deep dive in the nex
If you find the concepts of concurrency and async programming confusing in If you find the concepts of concurrency and async programming confusing in
general, I know where you're coming from and I have written some resources to general, I know where you're coming from and I have written some resources to
try to give a high level overview that will make it easier to learn Rusts try to give a high level overview that will make it easier to learn Rusts
`Futures` afterwards: `Future`s afterwards:
* [Async Basics - The difference between concurrency and parallelism](https://cfsamson.github.io/book-exploring-async-basics/1_concurrent_vs_parallel.html) * [Async Basics - The difference between concurrency and parallelism](https://cfsamson.github.io/book-exploring-async-basics/1_concurrent_vs_parallel.html)
* [Async Basics - Async history](https://cfsamson.github.io/book-exploring-async-basics/2_async_history.html) * [Async Basics - Async history](https://cfsamson.github.io/book-exploring-async-basics/2_async_history.html)

2
src/2_waker_context.md
View File

@@ -32,7 +32,7 @@ task-local storage and provide space for debugging hooks in later iterations.
## Understanding the `Waker` ## Understanding the `Waker`
One of the most confusing things we encounter when implementing our own `Futures` One of the most confusing things we encounter when implementing our own `Future`s
is how we implement a `Waker` . Creating a `Waker` involves creating a `vtable` is how we implement a `Waker` . Creating a `Waker` involves creating a `vtable`
which allows us to use dynamic dispatch to call methods on a _type erased_ trait which allows us to use dynamic dispatch to call methods on a _type erased_ trait
object we construct our selves. object we construct our selves.

4
src/3_generators_async_await.md
View File

@@ -6,7 +6,7 @@
>- See first hand why we need `Pin` >- See first hand why we need `Pin`
>- Understand what makes Rusts async model very memory efficient >- Understand what makes Rusts async model very memory efficient
> >
>The motivation for `Generators` can be found in [RFC#2033][rfc2033]. It's very >The motivation for `Generator`s can be found in [RFC#2033][rfc2033]. It's very
>well written and I can recommend reading through it (it talks as much about >well written and I can recommend reading through it (it talks as much about
>async/await as it does about generators). >async/await as it does about generators).
@@ -38,7 +38,7 @@ coroutines which Rust uses today.
### Combinators ### Combinators
`Futures 0.1` used combinators. If you've worked with `Promises` in JavaScript, `Futures 0.1` used combinators. If you've worked with `Promise`s in JavaScript,
you already know combinators. In Rust they look like this: you already know combinators. In Rust they look like this:
```rust,noplaypen,ignore ```rust,noplaypen,ignore

4
src/4_pin.md
View File

@@ -564,7 +564,7 @@ code.
certain operations on this value. certain operations on this value.
1. Most standard library types implement `Unpin`. The same goes for most 1. Most standard library types implement `Unpin`. The same goes for most
"normal" types you encounter in Rust. `Futures` and `Generators` are two "normal" types you encounter in Rust. `Future`s and `Generator`s are two
exceptions. exceptions.
5. The main use case for `Pin` is to allow self referential types, the whole 5. The main use case for `Pin` is to allow self referential types, the whole
@@ -605,7 +605,7 @@ extra care must be taken when implementing `Drop` for pinned types.
## Putting it all together ## Putting it all together
This is exactly what we'll do when we implement our own `Futures` stay tuned, This is exactly what we'll do when we implement our own `Future`s stay tuned,
we're soon finished. we're soon finished.
[rfc2349]: https://github.com/rust-lang/rfcs/blob/master/text/2349-pin.md [rfc2349]: https://github.com/rust-lang/rfcs/blob/master/text/2349-pin.md

14
src/6_future_example.md
View File

@@ -1,6 +1,6 @@
# Futures in Rust # Futures in Rust
We'll create our own `Futures` together with a fake reactor and a simple We'll create our own `Future`s together with a fake reactor and a simple
executor which allows you to edit, run an play around with the code right here executor which allows you to edit, run an play around with the code right here
in your browser. in your browser.
@@ -88,7 +88,7 @@ In all the examples you'll see in this chapter I've chosen to comment the code
extensively. I find it easier to follow along that way so I'll not repeat myself extensively. I find it easier to follow along that way so I'll not repeat myself
here and focus only on some important aspects that might need further explanation. here and focus only on some important aspects that might need further explanation.
Now that you've read so much about `Generators` and `Pin` already this should Now that you've read so much about `Generator`s and `Pin` already this should
be rather easy to understand. `Future` is a state machine, every `await` point be rather easy to understand. `Future` is a state machine, every `await` point
is a `yield` point. We could borrow data across `await` points and we meet the is a `yield` point. We could borrow data across `await` points and we meet the
exact same challenges as we do when borrowing across `yield` points. exact same challenges as we do when borrowing across `yield` points.
@@ -99,7 +99,7 @@ object will do more than just wrapping a `Future` so having this extra
abstraction gives some flexibility. abstraction gives some flexibility.
As explained in the [chapter about generators](./3_generators_pin.md), we use As explained in the [chapter about generators](./3_generators_pin.md), we use
`Pin` and the guarantees that give us to allow `Futures` to have self `Pin` and the guarantees that give us to allow `Future`s to have self
references. references.
## The `Future` implementation ## The `Future` implementation
@@ -107,7 +107,7 @@ references.
Futures has a well defined interface, which means they can be used across the Futures has a well defined interface, which means they can be used across the
entire ecosystem. entire ecosystem.
We can chain these `Futures` so that once a **leaf-future** is We can chain these `Future`s so that once a **leaf-future** is
ready we'll perform a set of operations until either the task is finished or we ready we'll perform a set of operations until either the task is finished or we
reach yet another **leaf-future** which we'll wait for and yield control to the reach yet another **leaf-future** which we'll wait for and yield control to the
scheduler. scheduler.
@@ -277,7 +277,7 @@ Since concurrency mostly makes sense when interacting with the outside world (or
at least some peripheral), we need something to actually abstract over this at least some peripheral), we need something to actually abstract over this
interaction in an asynchronous way. interaction in an asynchronous way.
This is the `Reactors` job. Most often you'll see reactors in Rust use a library This is the `Reactor`s job. Most often you'll see reactors in Rust use a library
called [Mio][mio], which provides non blocking APIs and event notification for called [Mio][mio], which provides non blocking APIs and event notification for
several platforms. several platforms.
@@ -654,7 +654,7 @@ The `async` keyword can be used on functions as in `async fn(...)` or on a
block as in `async { ... }`. Both will turn your function, or block, into a block as in `async { ... }`. Both will turn your function, or block, into a
`Future`. `Future`.
These `Futures` are rather simple. Imagine our generator from a few chapters These `Future`s are rather simple. Imagine our generator from a few chapters
back. Every `await` point is like a `yield` point. back. Every `await` point is like a `yield` point.
Instead of `yielding` a value we pass in, we yield the result of calling `poll` on Instead of `yielding` a value we pass in, we yield the result of calling `poll` on
@@ -675,7 +675,7 @@ Future got 1 at time: 1.00.
Future got 2 at time: 3.00. Future got 2 at time: 3.00.
``` ```
If these `Futures` were executed asynchronously we would expect to see: If these `Future`s were executed asynchronously we would expect to see:
```ignore ```ignore
Future got 1 at time: 1.00. Future got 1 at time: 1.00.

4
src/introduction.md
View File

@@ -1,6 +1,6 @@
# Futures Explained in 200 Lines of Rust # Futures Explained in 200 Lines of Rust
This book aims to explain `Futures` in Rust using an example driven approach, This book aims to explain `Future`s in Rust using an example driven approach,
exploring why they're designed the way they are, and how they work. We'll also exploring why they're designed the way they are, and how they work. We'll also
take a look at some of the alternatives we have when dealing with concurrency take a look at some of the alternatives we have when dealing with concurrency
in programming. in programming.
@@ -57,7 +57,7 @@ in Rust. If you like it, you might want to check out the others as well:
## Credits and thanks ## Credits and thanks
I'd like to take this chance to thank the people behind `mio`, `tokio`, I'd like to take this chance to thank the people behind `mio`, `tokio`,
`async_std`, `Futures`, `libc`, `crossbeam` which underpins so much of the `async_std`, `Future`s, `libc`, `crossbeam` which underpins so much of the
async ecosystem and and rarely gets enough praise in my eyes. async ecosystem and and rarely gets enough praise in my eyes.
A special thanks to [jonhoo](https://twitter.com/jonhoo) who was kind enough to A special thanks to [jonhoo](https://twitter.com/jonhoo) who was kind enough to