mutex: add `OwnedMutexGuard` for `Arc<Mutex<T>>`s (#2455)

This PR adds a new `OwnedMutexGuard` type and `lock_owned` and
`try_lock_owned` methods for `Arc<Mutex<T>>`.  This is pretty much the
same as the similar APIs added in #2421. 

I've also corrected some existing documentation that incorrectly
implied that the existing `lock` method cloned an internal `Arc` — I
think this may be a holdover from `tokio` 0.1's `Lock` type?

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

1 files changed, 121 insertions, 0 deletions

diff --git a/tokio/tests/sync_mutex_owned.rs b/tokio/tests/sync_mutex_owned.rs
new file mode 100644
index 00000000..eef966fd
--- /dev/null
+++ b/tokio/tests/sync_mutex_owned.rs
@@ -0,0 +1,121 @@
+#![warn(rust_2018_idioms)]
+#![cfg(feature = "full")]
+
+use tokio::sync::Mutex;
+use tokio::time::{interval, timeout};
+use tokio_test::task::spawn;
+use tokio_test::{assert_pending, assert_ready};
+
+use std::sync::Arc;
+use std::time::Duration;
+
+#[test]
+fn straight_execution() {
+    let l = Arc::new(Mutex::new(100));
+
+    {
+        let mut t = spawn(l.clone().lock_owned());
+        let mut g = assert_ready!(t.poll());
+        assert_eq!(&*g, &100);
+        *g = 99;
+    }
+    {
+        let mut t = spawn(l.clone().lock_owned());
+        let mut g = assert_ready!(t.poll());
+        assert_eq!(&*g, &99);
+        *g = 98;
+    }
+    {
+        let mut t = spawn(l.lock_owned());
+        let g = assert_ready!(t.poll());
+        assert_eq!(&*g, &98);
+    }
+}
+
+#[test]
+fn readiness() {
+    let l = Arc::new(Mutex::new(100));
+    let mut t1 = spawn(l.clone().lock_owned());
+    let mut t2 = spawn(l.clone().lock_owned());
+
+    let g = assert_ready!(t1.poll());
+
+    // We can't now acquire the lease since it's already held in g
+    assert_pending!(t2.poll());
+
+    // But once g unlocks, we can acquire it
+    drop(g);
+    assert!(t2.is_woken());
+    assert_ready!(t2.poll());
+}
+
+#[tokio::test]
+/// Ensure a mutex is unlocked if a future holding the lock
+/// is aborted prematurely.
+async fn aborted_future_1() {
+    let m1: Arc<Mutex<usize>> = Arc::new(Mutex::new(0));
+    {
+        let m2 = m1.clone();
+        // Try to lock mutex in a future that is aborted prematurely
+        timeout(Duration::from_millis(1u64), async move {
+            let mut iv = interval(Duration::from_millis(1000));
+            m2.lock_owned().await;
+            iv.tick().await;
+            iv.tick().await;
+        })
+        .await
+        .unwrap_err();
+    }
+    // This should succeed as there is no lock left for the mutex.
+    timeout(Duration::from_millis(1u64), async move {
+        m1.lock_owned().await;
+    })
+    .await
+    .expect("Mutex is locked");
+}
+
+#[tokio::test]
+/// This test is similar to `aborted_future_1` but this time the
+/// aborted future is waiting for the lock.
+async fn aborted_future_2() {
+    let m1: Arc<Mutex<usize>> = Arc::new(Mutex::new(0));
+    {
+        // Lock mutex
+        let _lock = m1.clone().lock_owned().await;
+        {
+            let m2 = m1.clone();
+            // Try to lock mutex in a future that is aborted prematurely
+            timeout(Duration::from_millis(1u64), async move {
+                m2.lock_owned().await;
+            })
+            .await
+            .unwrap_err();
+        }
+    }
+    // This should succeed as there is no lock left for the mutex.
+    timeout(Duration::from_millis(1u64), async move {
+        m1.lock_owned().await;
+    })
+    .await
+    .expect("Mutex is locked");
+}
+
+#[test]
+fn try_lock_owned() {
+    let m: Arc<Mutex<usize>> = Arc::new(Mutex::new(0));
+    {
+        let g1 = m.clone().try_lock_owned();
+        assert_eq!(g1.is_ok(), true);
+        let g2 = m.clone().try_lock_owned();
+        assert_eq!(g2.is_ok(), false);
+    }
+    let g3 = m.try_lock_owned();
+    assert_eq!(g3.is_ok(), true);
+}
+
+#[tokio::test]
+async fn debug_format() {
+    let s = "debug";
+    let m = Arc::new(Mutex::new(s.to_string()));
+    assert_eq!(format!("{:?}", s), format!("{:?}", m.lock_owned().await));
+}