Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More edits to the async chapter #4033

Merged
merged 31 commits into from
Sep 23, 2024
Merged
Changes from 1 commit
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
a42f27b
Ch. 17: Fix up diagrams
chriskrycho Aug 24, 2024
f812ed0
Ch. 17§00: second round of edits
chriskrycho Aug 24, 2024
c648c0e
Use immutable borrow of `TcpStream` when creating `BufReader`
bin-wang Aug 30, 2024
ef4a518
cargo init usage suggestion
ficcialfaint Aug 31, 2024
1de14c8
Ch. 17: start restructuring chapter
chriskrycho Aug 24, 2024
6b6b450
Upgrade to Rust 1.81
chriskrycho Sep 10, 2024
589ce6b
Merge pull request #4031 from rust-lang/rust-1.81
chriskrycho Sep 11, 2024
299fd1f
Clarify Cargo.toml generation with `cargo init`.
chriskrycho Sep 11, 2024
28a2444
Merge pull request #4024 from bin-wang/remove-mut
chriskrycho Sep 11, 2024
e2b7246
Merge pull request #4025 from ficcialfaint/cargo-init
chriskrycho Sep 11, 2024
d5932d2
Update build instructions: include mdbook plugins
chriskrycho Sep 11, 2024
2b07207
Merge pull request #4032 from rust-lang/updated-build-instructions
chriskrycho Sep 12, 2024
c552952
Ch. 17: rename `trpl::block_on` to `trpl::run`
chriskrycho Aug 24, 2024
cd12a1e
Ch. 17: more edits for first three sections
chriskrycho Sep 10, 2024
487c81d
Merge `main` into `async-edits` (Rust 1.81 update)
chriskrycho Sep 11, 2024
9b13b95
Upgrade Ch. 17 listings for Rust 1.81
chriskrycho Sep 10, 2024
3cfdf2d
Ch. 17: rework 17.03 (and overall structure) from my own analysis
chriskrycho Sep 10, 2024
97902d5
Ch. 17: rework 17.04 with my own edits and analysis
chriskrycho Sep 11, 2024
68049c6
Ch. 17: rework 17.05 with my own edits and analysis
chriskrycho Sep 11, 2024
0d8da8b
Ch. 17: fold together 17.03 and 17.04
chriskrycho Sep 11, 2024
7da825f
Ch. 17: Make the new 17.05 actually work as a deep dive!
chriskrycho Sep 11, 2024
6bdf1b7
Merge `main` into `async-edits`
chriskrycho Sep 12, 2024
1d3517c
Ch. 17: integrate a number of the outstanding review comments
chriskrycho Sep 11, 2024
c4d02bf
Ch. 17: address the rest of James’ review comments 🎉
chriskrycho Sep 12, 2024
c35b7d9
Ch. 17: address most of the rest of Carol's outstanding comments
chriskrycho Sep 12, 2024
453247c
Ch. 17: address Tim and Carol's outstanding comments
chriskrycho Sep 13, 2024
ccafd06
Ch. 17: Fix some typos!
chriskrycho Sep 13, 2024
6f5773e
Remove duplicate integration test from root
chriskrycho Sep 16, 2024
cc5db97
Ch. 17: rewrite 17.01 with a better example
chriskrycho Sep 13, 2024
573a6ca
Ch. 17: fix mdbook test output
chriskrycho Sep 20, 2024
b265249
Ch. 17: Fix spelling and internal links
chriskrycho Sep 23, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 32 additions & 9 deletions src/ch17-01-futures-and-syntax.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,30 @@
## Futures and the Async Syntax

Like other languages with async, Rust uses the `async` and `await` keywords for
async programming. (If you are familiar with other languages’ approach to async,
you may notice some significant differences, though.) In Rust, blocks and
functions can be marked `async`, and you can wait on the result of an `async`
function or block to resolve using the `await` keyword.
They key elements of asynchronous programming in Rust are *futures* and Rust’s
chriskrycho marked this conversation as resolved.
Show resolved Hide resolved
`async` and `await` keywords.

A future is a value that may not ready yet. Every future holds its own
chriskrycho marked this conversation as resolved.
Show resolved Hide resolved
information about the progress that has been made and what "ready" means. In
Rust, we say that types which implement the `Future` trait are futures. The
`async` keyword can be applied to blocks and functions to specify that they can
be interrupted and resumed. Within an async block or async function, you can use
the `await` keyword to wait for a future to become ready, called *awaiting a
future*. Each place you await a future within an async block or function is a
place that async block or function may get paused and resumed.
chriskrycho marked this conversation as resolved.
Show resolved Hide resolved

> Note: Many other languages use the `async` and `await` keywords for async
> programming. If you are familiar with other languages’ approach to async, you
> may notice some significant differences in how Rust does things, including how
> it handles the syntax. That is for good reason, as we will see!

That may all feel a bit abstract. Let’s write our first async program: a little
web scraper. This will have a fair bit of new syntax, but don’t worry. We will
chriskrycho marked this conversation as resolved.
Show resolved Hide resolved
explain it all as we go.

<!--
TODO: replace the example code here and the associated discussion with the web
scraper example we came up with.
-->

Let’s write our first async function, and call it:

Expand Down Expand Up @@ -37,8 +57,8 @@ learning what the syntax means, so let’s start there.

In Rust, writing `async fn` is equivalent to writing a function which returns a
*future* of the return type. That is, when the compiler sees a function like
`async fn hello` in Listing 17-1, it is basically equivalent to a function
defined like this instead:
`async fn hello` in Listing 17-1, it is equivalent to a function defined like
this instead:

```rust
use std::future::Future;
Expand Down Expand Up @@ -131,8 +151,11 @@ However, we get another compiler error here:
{{#include ../listings/ch17-async-await/listing-17-03/output.txt}}
```

The problem is that async code needs a *runtime*: a Rust crate which manages the
details of executing asynchronous code.
Rust won't allow us too mark `main` as `async`. The underlying problem is that
chriskrycho marked this conversation as resolved.
Show resolved Hide resolved
async code needs a *runtime*: a Rust crate which manages the details of
executing asynchronous code. A program's `main` function can initialize a
runtime, but it is not a runtime itself. (We will see more about why this is a
bit later.)

Most languages which support async bundle a runtime with the language. Rust does
not. Instead, there are many different async runtimes available, each of which
Expand Down
Loading