async/await: various edits #249

Be-ing · 2025-02-21T07:18:02Z

Mostly minor edits. I did rewrite one particularly long and wordy paragraph.

nrc

Thanks!

nrc · 2025-02-27T22:49:55Z

src/part-guide/async-await.md

@@ -29,7 +29,7 @@ To get up and running as quickly as possible, you need just a little boilerplate
 tokio = { version = "1", features = ["full"] }
 ```

-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):


I think the new formulation would be better with 'function' after main.

nrc · 2025-02-27T22:50:52Z

src/part-guide/async-await.md

@@ -38,7 +38,7 @@ async fn 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).


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

nrc · 2025-02-27T22:54:23Z

src/part-guide/async-await.md


-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.


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.

nrc · 2025-02-27T22:55:38Z

src/part-guide/async-await.md


-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.


I think quoting 'big' here makes sense since I'm using big colloquially or even metaphorically? Not sure

nrc · 2025-02-27T22:59:05Z

src/part-guide/async-await.md


-`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.


The 'it' here is referring to how the runtime is integrated with async and await, not the runtime itself.

async/await: various edits

58a50bc

Mostly minor edits. I did rewrite one particularly long and wordy paragraph.

nrc reviewed Feb 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

async/await: various edits #249

async/await: various edits #249

Be-ing commented Feb 21, 2025

nrc left a comment

nrc Feb 27, 2025

nrc Feb 27, 2025

nrc Feb 27, 2025

nrc Feb 27, 2025

nrc Feb 27, 2025


		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.


		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.


		`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.

async/await: various edits #249

Are you sure you want to change the base?

async/await: various edits #249

Conversation

Be-ing commented Feb 21, 2025

nrc left a comment

Choose a reason for hiding this comment

nrc Feb 27, 2025

Choose a reason for hiding this comment

nrc Feb 27, 2025

Choose a reason for hiding this comment

nrc Feb 27, 2025

Choose a reason for hiding this comment

nrc Feb 27, 2025

Choose a reason for hiding this comment

nrc Feb 27, 2025

Choose a reason for hiding this comment