Update docs

docs/golang/distributed/in-your-report.md

@@ -5,7 +5,7 @@
 
 - Discuss the system design and reasons for any decisions made.
 Consider using a diagram to aid your discussion.
-- Explain what data is sent over the network, when, and why it is necessary.  
+- Explain what data is sent over the network, when, and why it is necessary.
 - Discuss how your system might scale with the addition of other distributed components.
 - Briefly discuss your methodology for acquiring any results or measurements.
 - Identify how components of your system disappearing

docs/golang/distributed/step-1.md

@@ -18,8 +18,10 @@ You must be able to run the local controller as a client on a local machine, and
 Start by implementing a basic controller which can tell the logic engine to evolve Game of Life for the number of turns specified in `gol.Params.Turns`.
 You can achieve this by implementing a single, blocking RPC call to process all requested turns.
 
+### Test
+
 To test your implementation, type the following in the terminal of your **local controller**.
 
-```bash
+``` bash
 go test -v -run TestGol/-1$
 ```

docs/golang/distributed/step-2.md

@@ -7,12 +7,14 @@ You should report the number of cells that are still alive *every 2 seconds* to
 
 It is anticipated that you will run a ticker on the local controller and make an RPC call to the AWS node (worker/server/broker) every 2 seconds.
 
-The controller should then send an `AliveCellsCount` event to the `events` channel.  
+The controller should then send an `AliveCellsCount` event to the `events` channel.
 
 ![Step 2](/assets/cw_diagrams-Distributed_2.png)
 
+### Test
+
 To test your implementation, type the following in the terminal of your **local controller**.
 
-```bash
+``` bash
 go test -v -run TestAlive
 ```

docs/golang/distributed/step-3.md

@@ -7,8 +7,10 @@
 
 The local controller should be able to output the state of the board after all turns have completed as a PGM image.
 
+### Test
+
 To test your implementation, type the following in the terminal of your **local controller**.
 
-```bash
+``` bash
 go test -v -run TestPgm/-1$
 ```

docs/golang/distributed/step-4.md

@@ -10,21 +10,24 @@ Finally, the local controller should be able to manage the behaviour of the Gol
 - If `s` is pressed, the controller should generate a PGM file with the current state of the board.
 
 - If `q` is pressed, close the controller client program without causing an error on the Gol server.
-    ::: info Behaviour of new controller connected
-    A new controller should be able to take over interaction with the Gol engine.\
-    Note that you are free to define the nature of how a new controller can take over interaction.
-    Most likely the state will be reset.\
-    If you do manage to continue with the previous world this would be considered a form of [fault tolerance](/golang/extensions#fault-tolerance).
-    :::
+    >***NOTE:** Behaviour of new controller connected*
+    >
+    >*A new controller should be able to take over interaction with the Gol engine.\
+    >Note that you are free to define the nature of how a new controller can take over interaction.
+    >Most likely the state will be reset.\
+    >If you do manage to continue with the previous world this would be considered a form of [fault tolerance](/golang/extensions#fault-tolerance).*
+
 - If `k` is pressed, all components of the distributed system are shut down cleanly, and the system outputs a PGM image of the latest state.
 
 - If `p` is pressed, pause the processing *on the AWS node* and have the *controller* print the current turn that is being processed.\
 If `p` is pressed again resume the processing and have the controller print `Continuing`.
-It is necessary for `q` and `s` to work while the execution is paused.
+    > ***NOTE:**
+    > It is **necessary** for `q` and `s` to work while the execution is paused.*
+
+### Test
 
-\
-To test your implementation, type the following in the terminal of your **local controller**.
+To run the program and test the control rules manually, type the following in the terminal of your **local controller**.
 
-```bash
+``` bash
 go run .
 ```

docs/golang/distributed/step-5.md

@@ -1,7 +1,7 @@
 <!--@include: index.md-->
 #
 
-## Step 5 - New for 22 - go straight to Step 6
+## Step 5 (Consider going straight to Step 6)
 
 ![Step 5](/assets/cw_diagrams-Distributed_5.png)
 

docs/golang/overview.md

@@ -38,10 +38,14 @@ All parts of the skeleton are commented. All the code has been written in Go.
 
 You will not be required to write any C code. If you have any questions about the skeleton please ask a TA for help.
 
-::: warning Please note:
+::: warning Please note
 You **must not** modify any of the files ending in `_test.go`. We will be using these tests to judge the correctness of your implementation. We will undo any changes you make to them.
 :::
 
+::: warning For WSL2 users
+If you are using WSL2, ensure your skeleton is located within the WSL2 file system. Specifically, **your project should be located at `~/.../gol-skeleton`, NOT at `/mnt/.../gol-skeleton`**
+:::
+
 The skeleton code uses SDL.
 This is a basic graphics library which you already used in Imperative Programming unit.
 
@@ -74,7 +78,7 @@ There will be three separate submissions points on Blackboard - one for the repo
 - If you have multiple versions, only submit the ones you wish us to check for correctness (one zip for parallel and one for distributed). Other versions may be shared via OneDrive with Sion, Pui and Michael.
 :::
 
-::: warning Please note:
+::: warning Please note
 
 - Submitting different filenames or file formats (e.g. `.docx`, `.tex`, `.7z` or `.rar`) will result in a mark penalty.
 - **Each team member** has to upload an **identical copy** of the team's work.

docs/golang/parallel/in-your-report.md

@@ -7,3 +7,15 @@
 - Explain and analyse the benchmark results obtained. You may want to consider using graphs to visualise your benchmarks.
 - Analyse how your implementation scales as more workers are added.
 - Briefly discuss your methodology for acquiring any results or measurements.
+
+:::warning Note on measurements
+You might notice that the program displays the average computation turns per second in the console.
+
+> Completed Turns 5883    Alive Cells 5567    **Avg  980 turns/sec**
+
+This is intended to give you a **general sense** of how the program is performing compared to previous runs.
+
+**However, this measurement is informal and should NOT be used or cited in your report.**
+
+For formal analysis, please refer to the benchmark results.
+:::

docs/golang/parallel/step-1.md

@@ -36,7 +36,7 @@ Therefore, you only need to send the `FinalTurnComplete` event, with the list of
 
 ### Test
 
-To test your serial, single-threaded code, type the following in the terminal, all the tests ran should pass.
+To test your serial, single-threaded implementation, type the following in the terminal, all the tests ran should pass.
 
 ``` bash
 go test -v -run TestGol/-1$

docs/golang/parallel/step-2.md

@@ -13,7 +13,9 @@ The number of worker threads you should create is specified in `gol.Params.Threa
 
 You are free to design your system as you see fit, however, we encourage you to primarily use channels.
 
-To test your code, type the following in the terminal.
+### Test
+
+To test your implementation, type the following in the terminal.
 You can use tracing to verify the correct number of workers was used this time.
 
 ``` bash

docs/golang/parallel/step-3.md

@@ -11,14 +11,16 @@ Now using a ticker, report the number of cells that are still alive *every 2 sec
 
 To report the count use the `AliveCellsCount` event.
 
-To test your code, type the following in the terminal.
+### Test
+
+To test your implementation, type the following in the terminal.
 
 ``` bash
 go test -v -run TestAlive
 ```
 
 ### Troubleshooting
 
-You can check what the correct number of alive cells is by looking at the `.csv` files in the `check/alive/` folder. 
+You can check what the correct number of alive cells is by looking at the `.csv` files in the `check/alive/` folder.
 
 You might find that you are reporting the count for the turn before or turn after. If this happens the `CompletedTurns` might be what is wrong, not the count

docs/golang/parallel/step-4.md

@@ -9,7 +9,9 @@ Implement logic to output the state of the board after all turns have completed
 
 The output logic is very similar to the input logic from Step 1. Again, look at the file `gol/io.go` for the implementation details.
 
-To test your code, type the following in the terminal.
+### Test
+
+To test your implementation, type the following in the terminal.
 
 ``` bash
 go test -v -run TestPgm

docs/golang/parallel/step-5.md

@@ -10,7 +10,7 @@ Note that the running SDL provides you with a channel containing the relevant ke
     > ***NOTE:** Don't forget to send an `ImageOutputComplete` event after a PGM image is saved.*
 - If `q` is pressed, stop executing Gol computation, save the current state of the board as a PGM image, then terminate the program.
     > ***NOTE:** Your distributor should behave as following after `q` is pressed:*
-    > 
+    >
     > *Complete the current turn \
     > Send a `FinalTurnComplete` event \
     > Save the final state as PGM image and send an `ImageOutputComplete` event \
@@ -20,7 +20,8 @@ Note that the running SDL provides you with a channel containing the relevant ke
     > ***NOTE:**
     > It is **necessary** for `q` and `s` to work while the execution is paused.*
 
-\
+### Test
+
 To test the visualisation and control rules, type the following in the terminal.
 
 ::: code-group
@@ -40,4 +41,3 @@ You can also run the program and test the control rules manually by typing the f
 ``` bash
 go run .
 ```
-

docs/golang/parallel/step-6.md

@@ -9,7 +9,7 @@ You will need to utilise `CellFlipped` and `TurnComplete` events to achieve this
 
 Send `TurnComplete` events at the end of each turn, **even if you are about to send `FinalTurnComplete`**.
 
-Send `CellFlipped` events whenever a cell changes from alive to dead or from dead to alive. 
+Send `CellFlipped` events whenever a cell changes from alive to dead or from dead to alive.
 
 > *Don't forget to send `CellFlipped` events for every initially alive cell before the first `StateChange` is sent.*
 
@@ -19,7 +19,8 @@ Check out `gol/event.go` and `sdl/loop.go` for more details.
 > You can send more than one `CellsFlipped` event in a turn, i.e., each worker could send `CellsFlipped`.
 > Be careful not to send both `CellFlipped` and `CellsFlipped` events for the same cell, or you will flip it twice*
 
-\
+### Test
+
 To test the visualisation and control rules, type the following in the terminal.
 
 ::: code-group
@@ -40,8 +41,8 @@ You can also run the program and view the visualisation by typing the following
 go run .
 ```
 
-Finally, type the following in the terminal to make sure all tests are passing.
+Finally, type the following in the terminal to make sure all tests are passing with race detector.
 
 ``` bash
-go test -v
+go test -v -race
 ```

docs/index.md

@@ -8,7 +8,7 @@ You must report any change to your pairing to the unit director *before* startin
 
 It runs over 4 weeks (5 weeks including the reading week).
 ::: warning Note on deadline
-The deadline for submitting all your work is **30 November 13:00**
+The deadline for submitting all your work is **TBD**
 :::
 
 Talk to each other regularly and make sure you manage your team well.
@@ -21,7 +21,7 @@ Do not spend hours trying to debug on your own; use pair programming, seek help
 
 Do not have one team member do just the parallel task and the other do just the distributed task. There is significant overlap between the two. If you work separately then both team members will have to solve the same problems separately.
 
-Similarly, do not have one team member do the programming tasks and the other just write the report. You need an in-depth understanding of the code to write a good report. 
+Similarly, do not have one team member do the programming tasks and the other just write the report. You need an in-depth understanding of the code to write a good report.
 
 ## Useful Links
 

docs/rust/before-start.md

@@ -13,8 +13,6 @@
   \
   This book is for Rust masters.
 
-<!-- ### About asynchronous programming and concurrency -->
-
 ## Benchmarking
 
 The cousework skeleton provides you a basic benchmark under `benches/bench.rs`.

docs/rust/distributed/in-your-report.md

@@ -5,7 +5,7 @@
 
 - Discuss the system design and reasons for any decisions made.
 Consider using a diagram to aid your discussion.
-- Explain what data is sent over the network, when, and why it is necessary.  
+- Explain what data is sent over the network, when, and why it is necessary.
 - Discuss how your system might scale with the addition of other distributed components.
 - Briefly discuss your methodology for acquiring any results or measurements.
 - Identify how components of your system disappearing

docs/rust/distributed/index.md

@@ -1,5 +1,9 @@
 # Distributed Implementation
 
+<div class="warning custom-block" style="padding-top: 10px">
+<b>This guide is for the Rust version of the coursework, which is offered as an optional extension.</b>
+</div>
+
 In this stage, you are required to create an implementation that uses a number of
 AWS nodes to cooperatively calculate the new state of the Game of Life board,
 and communicate state between machines over a network.

docs/rust/distributed/step-0.md

@@ -13,15 +13,15 @@ To install protobuf, type
 
 ::: code-group
 
-```bash [WSL2]
+``` bash [WSL2]
 sudo apt install protobuf-compiler
 ```
 
-```bash [Ubuntu]
+``` bash [Ubuntu]
 sudo apt install protobuf-compiler
 ```
 
-```bash [macOS]
+``` bash [macOS]
 brew install protobuf
 ```
 
@@ -36,7 +36,7 @@ Add `C:\Program Files\protoc-xxx-win64\bin` to your **path** environment variabl
 
 To check if protobuf compiler is working, type
 
-```bash
+``` bash
 protoc --version
 ```
 
@@ -55,7 +55,7 @@ If you are using `git clone`, switch to the `distributed` branch by typing `git
 If you are using `Use this template`, please check `Include all branches` and switch to the `distributed` branch as well.
 :::
 
-::: tip For WSL2 users
+::: warning For WSL2 users
 If you are using WSL2, ensure your skeleton is located within the WSL2 file system. Specifically, **your project should be located at `~/.../gol-rs-skeleton`, NOT at `/mnt/.../gol-rs-skeleton`**
 :::
 
@@ -117,7 +117,22 @@ $ cargo run --release
 Open `controller/src/gol/distributor.rs`, you may find it similar to the parallel version, except we've made `remote_distributor()` an async function.
 
 In `example_rpc_call()`,
-you will see that we first convert a 2D world `Vec<Vec<CellValue>>` to bytes `Vec<u8>`.
+we connect to the server first.
+
+``` rust
+let mut client = ControllerHandlerClient::connect(format!("http://{}", server_addr)).await?;
+```
+
+The server address `server_addr` is defined in `Params` struct, and the `Params` struct is converted from `Args (controller/src/args.rs)` struct that defines command line arguments including the default server address.
+We used **[Clap](https://github.com/clap-rs/clap)** as the command line argument parser.
+
+To pass custom server address by command line argument, type (127.0.0.1:8030 in this case)
+
+``` bash
+cargo run --release -- --server_addr "127.0.0.1:8030"
+```
+
+After connected to the server, you will see that we create and convert a 2D world `Vec<Vec<CellValue>>` to bytes `Vec<u8>`.
 
 ``` rust
 let bytes = world.iter().flat_map(|row| row.as_bytes()).copied().collect();
@@ -144,13 +159,13 @@ Note that we also assert the correctness of the calculation performed by the ser
 match response {
     Ok(response) => {
         let msg = response.into_inner();
-        info!("response: {:?}", msg);
+        log::info!(target: "Distributor", "response: {:?}", msg);
         assert_eq!(
             msg.cells_count as usize,
             world.iter().flatten().filter(|cell| cell.is_alive()).count()
         );
     },
-    Err(e) => log::error!("Server error: {}", e),
+    Err(e) => log::error!(target: "Distributor", "Server error: {}", e),
 }
 ```
 
@@ -179,7 +194,7 @@ In `push_world()`, we extract the data from the request and save the `width` and
 ``` rust
 async fn push_world(&self, request: Request<World>) -> Result<Response<AliveCellsCount>, Status> {
     let world = request.into_inner(); // [!code highlight]
-    info!("request: {:?}", world);
+    log::info!("request: {:?}", world);
     *self.width.write().await = world.width; // [!code highlight]
     *self.height.write().await = world.height; // [!code highlight]
     ...
@@ -200,7 +215,7 @@ You can notice `width`, `height` and `cell_values` are wrapped with `RwLock` (re
 
 ``` rust
 pub struct Broker {
-    shutdown_tx: UnboundedSender<()>,
+    shutdown_tx: Sender<()>,
     width: RwLock<u32>, // [!code highlight]
     height: RwLock<u32>, // [!code highlight]
     cell_values: RwLock<Vec<Vec<CellValue>>>, // [!code highlight]