commit 750ea1b64454252f59659196d87ae04e6736cd9a
Author: realaravinth <realaravinth@batsense.net>
Date:   Thu Feb 24 22:05:32 2022 +0530

    init

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ea8c4bf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/target
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..831b493
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,98 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "hermit-abi"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bf2e165bb3457c8e098ea76f3e3bc9db55f87aa90d52d0e6be741470916aaa4"
+
+[[package]]
+name = "num_cpus"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19e64526ebdee182341572e50e9ad03965aa510cd94427a4549448f285e957a1"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e280fbe77cc62c91527259e9442153f4688736748d24660126286329742b4c6c"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7342d5883fbccae1cc37a2353b09c87c9b0f3afd73f5fb9bba687a1f733b029"
+dependencies = [
+ "unicode-xid",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "864d3e96a899863136fc6e99f3d7cae289dafe43bf2c5ac19b70df7210c0a145"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rust-async"
+version = "0.1.0"
+dependencies = [
+ "tokio",
+]
+
+[[package]]
+name = "syn"
+version = "1.0.86"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a65b3f4ffa0092e9887669db0eae07941f023991ab58ea44da8fe8e2d511c6b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-xid",
+]
+
+[[package]]
+name = "tokio"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2af73ac49756f3f7c01172e34a23e5d0216f6c32333757c2c61feb2bbff5a5ee"
+dependencies = [
+ "num_cpus",
+ "pin-project-lite",
+ "tokio-macros",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b557f72f448c511a979e2564e55d74e6c4432fc96ff4f6241bc6bded342643b7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "unicode-xid"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ccb82d61f80a663efe1f787a51b16b5a51e3314d6ac365b08639f52387b33f3"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..de347e8
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "rust-async"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[[bin]]
+name = "blocking"
+path = "./src/blocking.rs"
+
+[[bin]]
+name = "async-tokio"
+path = "./src/async-tokio.rs"
+
+[dependencies]
+# feature flags are documented in tokio's documentation https://docs.rs/tokio/latest/tokio/#feature-flags
+tokio = { version = "1", features = ["rt-multi-thread", "fs", "macros", "time"] }
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..e09b6d1
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,10 @@
+default: help
+
+async: ## Runs non-blocking program
+	cargo run --bin=async-tokio
+
+blocking: ## Runs blocking program
+	cargo run --bin=blocking
+
+help: ## Prints help for targets with comments
+	@cat $(MAKEFILE_LIST) | grep -E '^[a-zA-Z_-]+:.*?## .*$$' | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eb49239
--- /dev/null
+++ b/README.md
@@ -0,0 +1,17 @@
+# Blocking vs Non-blocking file I/O
+
+Blocking code is available in [blockin.rs](./src/blocking.rs] and
+non-blocking in [async-tokio.rs](./src/async-tokio.rs). 
+
+Both programs read their respective source files and print it to
+stdout.
+
+## Usage
+A simple Makefile is provided for convenience:
+
+```bash
+➜  rust-async git:(master) ✗ make help
+async                          Runs non-blocking program
+blocking                       Runs blocking program
+help                           Prints help for targets with comments
+```
diff --git a/src/async-tokio.rs b/src/async-tokio.rs
new file mode 100644
index 0000000..ce9600a
--- /dev/null
+++ b/src/async-tokio.rs
@@ -0,0 +1,36 @@
+use std::time::Duration;
+
+use tokio::fs;
+use tokio::time;
+
+async fn print_100() -> usize { // return type is to demonstrate syntax sugar that is available through "async" prefix
+    // actual return type is more complicated.
+    let mut count = 0;
+    while count < 10 {
+        println!("---------------SPAWNED FUTURE OUTPUT: {count}!!!!!--------");
+        time::sleep(Duration::from_nanos(1)).await;
+        count += 1;
+    }
+    count
+}
+
+#[tokio::main] // this macro expands into code that creates a runtime for executing futures 
+// when awaited, the future is sent to the runtime created by it.
+// I'm using a multi-threaded runtime(tokio feature flag "rt-multi-thread"), which creates schedules
+// = number of CPUs available by default
+async fn main() {
+    // working directory that is supplied by cargo is crate/program root
+
+    let future = fs::read_to_string("./src/async-tokio.rs");
+
+    // spawning a future is the same as backgrounding it
+    let spawn_handle = tokio::spawn(print_100());
+
+    let contents = future.await.unwrap();
+    // Rust futures are lazily evaluated, they have to be "awaited" for execution.
+    // When awaited, this line of execution is blocked until the future runs to completion
+    // rustc will complain about dead code if the following line is commented out:
+    println!("{contents}");
+
+    spawn_handle.await.unwrap(); // waiting for the spawned future to run to completion
+}
diff --git a/src/blocking.rs b/src/blocking.rs
new file mode 100644
index 0000000..a129cd7
--- /dev/null
+++ b/src/blocking.rs
@@ -0,0 +1,6 @@
+use std::fs;
+fn main() {
+    // working directory that is supplied by cargo is crate/program root
+    let contents = fs::read_to_string("./src/blocking.rs").unwrap();
+    println!("{contents}");
+}