Merge pull request #67 from ghimiresdp/feature/arc-mutex

Added Arc Mutex example

Author: ghimiresdp

README.md

@@ -181,6 +181,7 @@ cargo test --bin huffman
 - [Box Pointers](advanced/smart-pointers/src/box.rs) `cargo run --bin box`
 - [Reference Counters (`Rc`)](advanced/smart-pointers/src/rc.rs) `cargo run --bin rc`
 - [`RefCell`](advanced/smart-pointers/src/refcell.rs)`cargo run --bin refcell`
+- [`Arc Mutex`](advanced/smart-pointers/src/arc-mutex.rs)`cargo run --bin arc-mutex`
 
 ### 5.9. Specialized topics
 - Writing a custom allocator

advanced/smart-pointers/Cargo.toml

@@ -19,3 +19,7 @@ path = 'src/rc.rs'
 [[bin]]
 name = 'refcell'
 path = 'src/refcell.rs'
+
+[[bin]]
+name = 'arc-mutex'
+path = 'src/arc-mutex.rs'

advanced/smart-pointers/src/arc-mutex.rs

@@ -0,0 +1,173 @@
+use std::sync::{Arc, Mutex};
+use std::thread;
+use std::time::Duration;
+/**
+ * # Mutex
+ * Mutex ( MUTual EXclusion ) is a synchronization primitive that allows multiple
+ * threads to access a shared resource safely.
+ *
+ * Think mutex as a rented bike which can be used by multiple users, however,
+ * one should first reserve before being able to ride. The second user will be
+ * able to ride the bike only once the first user returns it to the owner.
+ *
+ * In case of mutex, a thread must lock the resource to be able to mutate it.
+ * after its operation is completed, the thread releases the lock and the next
+ * thread in the queue will be able to use it.
+ *
+ * when we lock a mutex, it returns a smart pointer to the resource called a
+ * MutexGuard which is a smart pointer that releases the lock when it goes out
+ * of scope.
+ */
+
+struct Rent {
+    user: String,
+    time: usize,
+}
+
+struct Bike {
+    ride_time: usize,
+}
+
+impl Bike {
+    fn new() -> Self {
+        Self { ride_time: 0 }
+    }
+
+    fn ride(&mut self, time: usize) {
+        println!("A {} hours bike ride has been started", time);
+        thread::sleep(Duration::from_secs(time as u64));
+        self.ride_time += time;
+        println!("ride complete!!");
+    }
+}
+
+impl Rent {
+    fn new(user: &str, time: usize) -> Self {
+        Self {
+            user: user.to_owned(),
+            time,
+        }
+    }
+}
+
+fn main() {
+    // in this example, a bike will be rented by 4 different people, however
+    // it is not possible to ride a bike by all at once, so mutex guard will
+    // make sure that the bike is mutated by only one user.
+    //
+    println!("\n{}", "=".repeat(50));
+
+    let bike = Arc::new(Mutex::new(Bike::new()));
+    let rentals = vec![
+        Rent::new("Alice", 5),
+        Rent::new("Bob", 2),
+        Rent::new("Charlie", 4),
+        Rent::new("Daniel", 3),
+    ];
+
+    // we keep track of thread handles here
+    let mut handles = vec![];
+
+    // iterate through rentals
+    for rent in rentals {
+        // clone for each thread
+        let bike = Arc::clone(&bike);
+
+        // create a thread handle
+        // here we need to have the ownership of the bike to be able to mutate
+        // so we need to use move along with closure
+        let handle = thread::spawn(move || {
+            // since the process is threaded, waiting order might
+            // differ on each execution.
+            println!("[{:^20}] waiting!!", &rent.user.clone());
+
+            let mut rental = bike.lock().unwrap();
+            println!("{}", "-".repeat(50));
+            println!(
+                "The bike is now rented by {} for {} hours.",
+                &rent.user.clone(),
+                &rent.time
+            );
+
+            // the ride() method emulated bike ride and makes the thread sleep
+            // for the given time in seconds. Until the thread is completed,
+            // another thread will not be able to lock the bike so it will wait
+            // until previous thread is released.
+            rental.ride(rent.time);
+
+            println!("The bike ran {} hours.", rental.ride_time);
+            println!("[ The bike has been returned ]")
+        });
+        handles.push(handle);
+    }
+
+    for handle in handles {
+        handle.join().unwrap();
+    }
+    println!("{}", "=".repeat(50));
+    println!(
+        "The bike had a total ride of {} hours",
+        bike.as_ref().lock().unwrap().ride_time
+    );
+}
+// Output (order might differ) due to threading
+// ==================================================
+// [       Alice        ] waiting!!
+// --------------------------------------------------
+// The bike is now rented by Alice for 5 hours.
+// [      Charlie       ] waiting!!
+// [       Daniel       ] waiting!!
+// A 5 hours bike ride has been started
+// [        Bob         ] waiting!!
+// ride complete!!
+// The bike ran 5 hours.
+// [ The bike has been returned ]
+// --------------------------------------------------
+// The bike is now rented by Charlie for 4 hours.
+// A 4 hours bike ride has been started
+// ride complete!!
+// The bike ran 9 hours.
+// [ The bike has been returned ]
+// --------------------------------------------------
+// The bike is now rented by Daniel for 3 hours.
+// A 3 hours bike ride has been started
+// ride complete!!
+// The bike ran 12 hours.
+// [ The bike has been returned ]
+// --------------------------------------------------
+// The bike is now rented by Bob for 2 hours.
+// A 2 hours bike ride has been started
+// ride complete!!
+// The bike ran 14 hours.
+// [ The bike has been returned ]
+// ==================================================
+// The bike had a total ride of 14 hours
+
+#[cfg(test)]
+mod test {
+    use std::sync::{Arc, Mutex};
+
+    use crate::Bike;
+
+    #[test]
+    fn test_lock_unlock() {
+        let bike = Arc::new(Mutex::new(Bike::new()));
+
+        // Lock and mutate
+        {
+            let mut guard = bike.lock().unwrap();
+            guard.ride(5);
+            assert_eq!(guard.ride_time, 5);
+            // guard goes out of scope here, lock is released
+        }
+        // remember, the first lock is released here as the guard goes out of
+        // scope, so we can lock it again otherwise it will result in a deadlock
+        // and the program will hang  forever.
+        // Lock again and mutate
+        {
+            let mut guard = bike.lock().unwrap();
+            guard.ride(3); // total ride time is now 8
+            assert_eq!(guard.ride_time, 8);
+        }
+    }
+}