added readmes, spelling, minor fixes

cfsamson · cfsamson · commit e2ce4c085cf0 · 2024-01-15T00:18:02.000+01:00
diff --git a/.DS_Store b/.DS_Store
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 target/
-Cargo.lock
+Cargo.lock
+.vscode
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Asynchronous Programming in Rust
 
-This is the repository for the book: Asynchronous Programming in Rust - learn asynchronous programming from first principles.
+This is the repository for the book: _Asynchronous Programming in Rust_.
 
 Written by Carl Fredrik Samson, published by Packt
 
@@ -12,9 +12,9 @@ Each chapter has its own folder in this repository. Each example is organized as
 
 When encountering examples in the book, you might find it easier to read the code in the repository since you'll be able to open it up in the editor of your choice and have appropriate highlighting and formatting.
 
-Even if you prefer to write the examples from the book line by line, you'll need the repository for `delayserver` and `corofy` which is two tools I wrote to help in the learning process.
+Even if you only write the examples directly from the book line by line, you'll need the repository for `delayserver` and `corofy` which is two tools I wrote to help in the learning process.
 
-## I'll be going on a plane, how can I use the repository in an offline situation?
+## I'm going on a plane, how can I use the repository in an offline situation?
 
 You'll need to install both `delayserver` and `corofy` locally on your machine while you're online. The process is described below.
 
@@ -28,10 +28,12 @@ Most of the examples will use a program called delayserver that's provided in th
 You have two options for running the delayserver:
 
 1. Go to the folder named `/delayserver` and write `cargo run` in a separate terminal window and leave it running there
-2. Go to the delayserver and install the server by writing `cargo install --force --path .`. By doing so you install the program locally in you PATH so you can run it from any location by simply writing `delayserver` and leave the terminal process running.
+2. Go to the same folder and install the server by writing `cargo install --force --path .`. By doing so you install the program locally in you PATH so you can run it from any location by simply writing `delayserver` and leave the terminal process running.
+
+How delayserver works is described in the book, but you'll also find the relavant information in its root folder.
 
 ## Corofy
 
-Corofy is another tool that we'll use from chapter 7 onwards. I recommend installing this tool by entering the folder `ch7/corofy` and installing it on your machine by writing `cargo install --force --path .`
+Corofy is another tool that we'll use from chapter 7 onwards. I recommend installing this tool locally by entering the folder `ch7/corofy` and installing it on your machine by writing `cargo install --force --path .`
 
 Asynchronous Programming in Rust, published by Packt
diff --git a/ch01/README.md b/ch01/README.md
@@ -0,0 +1,3 @@
+# Chapter 1 - Concurrency and Asynchronous Programming: A Detailed Overview
+
+This folder contains the code examples for Chapter 1.
diff --git a/ch02/README.md b/ch02/README.md
@@ -0,0 +1,3 @@
+# Chapter 2 - How Programming Languages Model Asynchronous Program Flow
+
+This folder contains the code examples for Chapter 2.
diff --git a/ch03/README.md b/ch03/README.md
@@ -0,0 +1,3 @@
+# Chapter 3 - Understanding OS-backed Event Queues, System Calls and Cross Platform Abstractions
+
+This folder contains the code examples for Chapter 3.
diff --git a/ch04/README.md b/ch04/README.md
@@ -0,0 +1,3 @@
+# Chapter 4 - Create Your Own Event Queue
+
+This folder contains the code examples for Chapter 4.
diff --git a/ch05/How-to-MacOS-M.md b/ch05/How-to-MacOS-M.md
@@ -1,4 +1,4 @@
-# How to run these examples on a Mac with an M-series chip
+# How to run these examples on a Mac with an M-seriXes chip
 
 Newer Macs use a chip using the ARM ISA, which won't work out of the box with
 these examples. However, these Macs ship with an emulation software called Rosetta
@@ -16,33 +16,21 @@ It should report `i386`.
 3. Run `rustup target add x86_64-apple-darwin`
 4. You can now run the examples using the command: `cargo run --target x86_64-apple-darwin`
 
-## Important
+## Note
 
 In the example: "c-fibers" and "d-fibers-closure" (and "e-fibers-windows"
-since it works on both platforms), you'll notice that we set a slightly
-different name when the function is exported on MacOS and even though we
-write `#[no_mangle]`, the compiler prepends the name of the function with an
-underscore `_`.
+since it works on both platforms), you'll notice that we use a conditional
+compilation attribute for `macos` targets.
 
 This is due to the platform ABI on MacOS which expects functions to be prepended
-with `_`. So, when we call the function in our inline assembly later on
-we need to account for that. For example by changing:
+with `_`. So, LLVM will by default add an underscore to our functions even if we
+tag them with `#[no_mangle]`.
 
-```rust
-asm!("call switch", in("rdi") old, in("rsi") new, clobber_abi("C"));
-```
-
-To:
-
-```rust
-asm!("call _switch", in("rdi") old, in("rsi") new, clobber_abi("C"));
-```
-
-Another workaround is to strip the first byte of the name on
-export by adding the attribute below to the `switch` function:
+The workaround we use is to strip the first byte of the name that's exported
+by LLVM on MacOS by adding the attribute below to the `switch` function:
 
 ```rust
 #[cfg_attr(target_os = "macos", export_name = "\x01switch")]
 ```
 
-You can read more about this here: https://github.com/rust-lang/rust/issues/35052#issuecomment-235420755
+You can read more about this here: <https://github.com/rust-lang/rust/issues/35052#issuecomment-235420755>
diff --git a/ch05/README.md b/ch05/README.md
@@ -0,0 +1,10 @@
+# Chapter 5 - Creating Our Own Fibers
+
+This folder contains the code examples for Chapter 5.
+
+## Note
+
+For MacOS users running M-family chips (most newer Macs), there is a few
+simple steps you can take to get the example running on your machine.
+
+It's explained step-by-step in [How-to-MacOS-M.md](./How-to-MacOS-M.md).
diff --git a/ch08/README.md b/ch08/README.md
@@ -0,0 +1,10 @@
+# Chapter 7 - Coroutines and async/await
+
+This folder contains the code examples for Chapter 7.
+
+## Note
+
+This folder also contains `corofy` that you'll need to install locally since
+you need it in this and the following chapters.
+
+You'll find all the details on how to do this both in the book and in the [corofy](./corofy/) folder.
diff --git a/ch08/corofy/RADME.md b/ch08/corofy/RADME.md
@@ -1,6 +1,6 @@
 # Corofy
 
-This tool aims to explain a few things about corotines, and
+This tool aims to explain a few things about coroutines, and
 by extension, async/await in Rust.
 
 The tool will take an input file like provided below and re-write
@@ -11,27 +11,56 @@ This way we can create examples easier and change them around and
 see what happens to the generated code.
 
 The tool will not remove anything from the file, but it will comment out
-the functions marked with `coro`, and re-arrange the transformation of them so
+the functions marked with `coroutine`, and re-arrange the transformation of them so
 that they're placed last in the file.
 
-The output will both contain the original `coro` function (commented out), and
+The output will both contain the original `coroutine` function (commented out), and
 comments explaining where the different parts of the original code is in the
 state machine.
 
+## Installation
+
+You can install locally on your computer to run the examples via the command line by
+entering the crate folder and writing:
+
+```
+
+cargo install --path .
+```
+
+You can avoid installing the project by using a more contrived syntax when using the tool
+to rewrite the example files like this:
+
+```
+
+cargo run -- [path-to-file] [optional-out-path]
+```
+
 ## Note
 
 This tool is very brittle. I can only guarantee it will correctly re-write the exact
 examples we go through in the book and in this repository. To name a few things it won't
 support:
 
 - Leaf coroutines (the ones created by Http::get) that returns anything else than `Future<Output=String>` (however, it should be possible with relatively minor effort to rewrite it to at least return `Future<Output=Vec<u8>>` to give it slightly more flexibility. Have a go if you want to!)
-- Non-leaf corotines that return anything else than `Future<Output=()>`
+- Non-leaf coroutines that return anything else than `Future<Output=()>`
 - Borrowing across wait points of any kind
-- any variable or function names containing the word "coro" will cause the program to fail, it must only be used in front of the specific functions that you want to re-write (however, writing the word `coro` in a comment should be fine :))
+- any variable or function names containing the word "coroutine" will cause the program to fail, it must only be used in front of the specific functions that you want to re-write (however, writing the word `coroutine` in a comment should be fine :))
 - Oh, and all futures have an Output type of `String` even if they don't return anything. This simplifies the code a bit, and without access to type information outside of the file we're parsing, we can't really rely on getting the types correctly anyway.
 - and much, much more
 
-Using procedual macros would be a preferred way to solve this. You can take a look at [https://github.com/alexcrichton/futures-await](https://github.com/alexcrichton/futures-await) if you want to see an example of that for Rust async/await.
+## Why don't you implement this as a macro instead?
+
+Using procedural macros would be a preferred way to solve this for more serious use.
+The only downside with macros, is that it's not so easy to see the generated code which
+is one of the key points for us. We want to inspect the transformations so we
+can learn from them.
+
+We'll also rely on `corofy` to generate the boilerplate for
+our state machines in the next chapters so we can expand on them manually to learn
+about `Waker` and `Pin`. This would not be possible if we used macros.
+
+There is already a macro implementation used for prototyping async/await. You can take a look at [https://github.com/alexcrichton/futures-await](https://github.com/alexcrichton/futures-await) if you want to see an example of how this can be implemented using macros.
 
 ## Usage
 
@@ -43,24 +72,6 @@ If no destination path is provided, it will default to writing to the same
 directory where the src file is located and adding the postfix "_corofied" to the
 file name.
 
-## Installation
-
-You can install locally on your computer to run the examples via the command line by
-entering the crate folder and writing:
-
-```
-
-cargo install --path .
-```
-
-You can avoid installing the project by using a more contrived syntax when using the tool
-to rewrite the example files like this:
-
-```
-
-cargo run -- [path-to-file] [optional-out-path]
-```
-
 ## Detailed explanation
 
 When installed you can give it a file using normal Rust code and our
diff --git a/ch09/.DS_Store b/ch09/.DS_Store
diff --git a/ch09/README.md b/ch09/README.md
@@ -0,0 +1,3 @@
+# Chapter 8 - Runtimes, Wakers and the Reactor-Executor Pattern
+
+This folder contains the code examples for Chapter 8.
diff --git a/ch09/b-reactor-executor/.DS_Store b/ch09/b-reactor-executor/.DS_Store
diff --git a/ch10/README.md b/ch10/README.md
@@ -0,0 +1,3 @@
+# Chapter 9 - Coroutines, Self-referential Structs and Pinning
+
+This folder contains the code examples for Chapter 9.
diff --git a/ch11/NOTES.md b/ch11/NOTES.md
diff --git a/ch11/README.md b/ch11/README.md
@@ -0,0 +1,3 @@
+# Chapter 10 - Create Your Own Runtime
+
+This folder contains the code examples for Chapter 10.

-Original file line number
+Diff line change
@@ @@ -1,2 +1,3 @@ @@
 target/
 -Cargo.lock
 +Cargo.lock
 +.vscode
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Chapter 1 - Concurrency and Asynchronous Programming: A Detailed Overview`
	`2`	`+`
	`3`	`+This folder contains the code examples for Chapter 1.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Chapter 2 - How Programming Languages Model Asynchronous Program Flow`
	`2`	`+`
	`3`	`+This folder contains the code examples for Chapter 2.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Chapter 3 - Understanding OS-backed Event Queues, System Calls and Cross Platform Abstractions`
	`2`	`+`
	`3`	`+This folder contains the code examples for Chapter 3.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Chapter 4 - Create Your Own Event Queue`
	`2`	`+`
	`3`	`+This folder contains the code examples for Chapter 4.`