async/await: various edits #249
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Mostly minor edits. I did rewrite one particularly long and wordy paragraph.
nrc
reviewed
Feb 27, 2025
| ``` | ||
|
|
||
| And you'll use the `tokio::main` annotation on your `main` function so that it can be an async function (which is otherwise not permitted in Rust): | ||
| And you'll annotate your `main` with the `tokio::main` macro so that it can be an async function (which is otherwise not permitted in Rust): |
There was a problem hiding this comment.
I think the new formulation would be better with 'function' after main.
| That's it! You're ready to write some asynchronous code! | ||
|
|
||
| The `#[tokio::main]` annotation initializes the Tokio runtime and starts an async task for running the code in `main`. Later in this guide we'll explain in more detail what that annotation is doing and how to use async code without it (which will give you more flexibility). | ||
| The `#[tokio::main]` macro initializes the Tokio runtime and starts an async task for running the code in `main`. Later in this guide we'll explain in more detail what that annotation is doing and how to use async code without it (which will give you more flexibility). |
There was a problem hiding this comment.
I prefer annotation - it describes what it is/how it works rather than how it is implemented (and avoids potential confusion with the more common ! macro usage
| We've used the term 'async task' quite a bit in an informal way in the previous chapter and this one. In that sense, the term means a logical sequence of execution; analogous to a thread but managed within a program rather than externally by the OS. It is often useful to think in terms of tasks, however, Rust itself has no concept of a task and the term is used to mean different things! It is confusing! To make it worse, runtimes do have a concept of a task and different runtimes have slightly different concepts of tasks. | ||
|
|
||
| From here on in, I'm going to try to be precise about the terminology around tasks. When I use just 'task' I mean the abstract concept of a sequence of computation that may occur concurrently with other tasks. I'll use 'async task' to mean exactly the same thing, but in contrast to a task which is implemented as an OS thread. I'll use 'runtime's task' to mean whatever kind of task a runtime imagines, and 'tokio task' (or some other specific runtime) to mean Tokio's idea of a task. | ||
| From here on in, we'll be more precise about the terminology around tasks. A "task", unqualified, refers to the abstract concept of a sequence of computation that may occur concurrently with other tasks. An "async task" means exactly the same thing, but in contrast to a task which is implemented as an OS thread. A "runtime's task" means whatever kind of task a runtime imagines, and "tokio task" (or some other specific runtime) means Tokio's idea of a task. |
There was a problem hiding this comment.
I think single quotes are more appropriate since I'm not quoting anyone, but highlighting a part of speech (perhaps that an British vs American English distinction?). I kind of like using the future tense and first person perspective (though happy to change I to we) because this is setting conventions for the book rather than claiming them as universal conventions.
| From here on in, we'll be more precise about the terminology around tasks. A "task", unqualified, refers to the abstract concept of a sequence of computation that may occur concurrently with other tasks. An "async task" means exactly the same thing, but in contrast to a task which is implemented as an OS thread. A "runtime's task" means whatever kind of task a runtime imagines, and "tokio task" (or some other specific runtime) means Tokio's idea of a task. | ||
|
|
||
| An async task in Rust is just a future (usually a 'big' future made by combining many others). In other words, a task is a future which is executed. However, there are times when a future is 'executed' without being a runtime's task. This kind of a future is intuitively a *task* but not a *runtime's task*. I'll spell this out more when we get to an example of it. | ||
| An async task in Rust is just a future (usually a big future made by combining many others). In other words, a task is a future which is executed. However, there are times when a future is executed without being a runtime's task. This kind of a future is intuitively a *task* but not a *runtime's task*. We'll look at an example of this in more detail later. |
There was a problem hiding this comment.
I think quoting 'big' here makes sense since I'm using big colloquially or even metaphorically? Not sure
| We've described `await` quite operationally so far (it runs a future, producing a result). How does `await` fit into the model of [async tasks and concurrency](./concurrency.md#async-programming) discussed in the previous chapter? First, let's consider pure sequential code: calling a non-async function simply continues the current task by executing the code in the function. By contrast, calling an async function only finds the code to run, but doesn't run it. To run the async function, the `await` operator continues execution of the current task, or if the current task can't continue right now, gives another task an opportunity to continue. | ||
|
|
||
| `await` can only be used inside an async context, for now that means inside an async function (we'll see more kinds of async contexts later). To understand why, remember that `await` might hand over control to the runtime so that another task can execute. There is only a runtime to hand control to in an async context. For now, you can imagine the runtime like a global variable which is only accessible in async functions, we'll explain later how it really works. | ||
| `await` can only be used inside an async context, for now that means inside an async function (we'll see more kinds of async contexts later). To understand why, remember that `await` might hand over control to the runtime so that another task can execute. There is only a runtime to hand control to in an async context. For now, you can imagine the runtime like a global variable which is only accessible in async functions. We'll explain later how runtimes really work. |
There was a problem hiding this comment.
The 'it' here is referring to how the runtime is integrated with async and await, not the runtime itself.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Mostly minor edits. I did rewrite one particularly long and wordy paragraph.