Add comments explaining we uphold unsafety contracts

Amanieu · Jun 6, 2019 · e616a27 · e616a27
1 parent 67f83c5
commit e616a27
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 10 deletions.
diff --git a/lock_api/src/mutex.rs b/lock_api/src/mutex.rs
@@ -172,6 +172,7 @@ impl<R: RawMutex, T: ?Sized> Mutex<R, T> {
     #[inline]
     pub fn lock(&self) -> MutexGuard<'_, R, T> {
         self.raw.lock();
+        // SAFETY: The lock is held, as required.
         unsafe { self.guard() }
     }
 
@@ -184,7 +185,12 @@ impl<R: RawMutex, T: ?Sized> Mutex<R, T> {
     /// This function does not block.
     #[inline]
     pub fn try_lock(&self) -> Option<MutexGuard<'_, R, T>> {
-        if self.raw.try_lock() { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 
     /// Returns a mutable reference to the underlying data.
@@ -253,7 +259,12 @@ impl<R: RawMutexTimed, T: ?Sized> Mutex<R, T> {
     /// be unlocked when the guard is dropped.
     #[inline]
     pub fn try_lock_for(&self, timeout: R::Duration) -> Option<MutexGuard<'_, R, T>> {
-        if self.raw.try_lock_for(timeout) { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock_for(timeout) {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 
     /// Attempts to acquire this lock until a timeout is reached.
@@ -263,7 +274,12 @@ impl<R: RawMutexTimed, T: ?Sized> Mutex<R, T> {
     /// be unlocked when the guard is dropped.
     #[inline]
     pub fn try_lock_until(&self, timeout: R::Instant) -> Option<MutexGuard<'_, R, T>> {
-        if self.raw.try_lock_until(timeout) { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock_until(timeout) {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 }
 

diff --git a/lock_api/src/remutex.rs b/lock_api/src/remutex.rs
@@ -246,6 +246,7 @@ impl<R: RawMutex, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T> {
     #[inline]
     pub fn lock(&self) -> ReentrantMutexGuard<'_, R, G, T> {
         self.raw.lock();
+        // SAFETY: The lock is held, as required.
         unsafe { self.guard() }
     }
 
@@ -258,7 +259,12 @@ impl<R: RawMutex, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T> {
     /// This function does not block.
     #[inline]
     pub fn try_lock(&self) -> Option<ReentrantMutexGuard<'_, R, G, T>> {
-        if self.raw.try_lock() { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 
     /// Returns a mutable reference to the underlying data.
@@ -327,7 +333,12 @@ impl<R: RawMutexTimed, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T> {
     /// be unlocked when the guard is dropped.
     #[inline]
     pub fn try_lock_for(&self, timeout: R::Duration) -> Option<ReentrantMutexGuard<'_, R, G, T>> {
-        if self.raw.try_lock_for(timeout) { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock_for(timeout) {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 
     /// Attempts to acquire this lock until a timeout is reached.
@@ -337,7 +348,12 @@ impl<R: RawMutexTimed, G: GetThreadId, T: ?Sized> ReentrantMutex<R, G, T> {
     /// be unlocked when the guard is dropped.
     #[inline]
     pub fn try_lock_until(&self, timeout: R::Instant) -> Option<ReentrantMutexGuard<'_, R, G, T>> {
-        if self.raw.try_lock_until(timeout) { Some(unsafe { self.guard() }) } else { None }
+        if self.raw.try_lock_until(timeout) {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.guard() })
+        } else {
+            None
+        }
     }
 }
 

diff --git a/lock_api/src/rwlock.rs b/lock_api/src/rwlock.rs
@@ -320,6 +320,7 @@ impl<R: RawRwLock, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn read(&self) -> RwLockReadGuard<'_, R, T> {
         self.raw.lock_shared();
+        // SAFETY: The lock is held, as required.
         unsafe { self.read_guard() }
     }
 
@@ -332,7 +333,12 @@ impl<R: RawRwLock, T: ?Sized> RwLock<R, T> {
     /// This function does not block.
     #[inline]
     pub fn try_read(&self) -> Option<RwLockReadGuard<'_, R, T>> {
-        if self.raw.try_lock_shared() { Some(unsafe { self.read_guard() }) } else { None }
+        if self.raw.try_lock_shared() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.read_guard() })
+        } else {
+            None
+        }
     }
 
     /// Locks this `RwLock` with exclusive write access, blocking the current
@@ -346,6 +352,7 @@ impl<R: RawRwLock, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn write(&self) -> RwLockWriteGuard<'_, R, T> {
         self.raw.lock_exclusive();
+        // SAFETY: The lock is held, as required.
         unsafe { self.write_guard() }
     }
 
@@ -358,7 +365,12 @@ impl<R: RawRwLock, T: ?Sized> RwLock<R, T> {
     /// This function does not block.
     #[inline]
     pub fn try_write(&self) -> Option<RwLockWriteGuard<'_, R, T>> {
-        if self.raw.try_lock_exclusive() { Some(unsafe { self.write_guard() }) } else { None }
+        if self.raw.try_lock_exclusive() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.write_guard() })
+        } else {
+            None
+        }
     }
 
     /// Returns a mutable reference to the underlying data.
@@ -461,6 +473,7 @@ impl<R: RawRwLockTimed, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn try_read_for(&self, timeout: R::Duration) -> Option<RwLockReadGuard<'_, R, T>> {
         if self.raw.try_lock_shared_for(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.read_guard() })
         } else {
             None
@@ -476,6 +489,7 @@ impl<R: RawRwLockTimed, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn try_read_until(&self, timeout: R::Instant) -> Option<RwLockReadGuard<'_, R, T>> {
         if self.raw.try_lock_shared_until(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.read_guard() })
         } else {
             None
@@ -491,6 +505,7 @@ impl<R: RawRwLockTimed, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn try_write_for(&self, timeout: R::Duration) -> Option<RwLockWriteGuard<'_, R, T>> {
         if self.raw.try_lock_exclusive_for(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.write_guard() })
         } else {
             None
@@ -506,6 +521,7 @@ impl<R: RawRwLockTimed, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn try_write_until(&self, timeout: R::Instant) -> Option<RwLockWriteGuard<'_, R, T>> {
         if self.raw.try_lock_exclusive_until(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.write_guard() })
         } else {
             None
@@ -532,6 +548,7 @@ impl<R: RawRwLockRecursive, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn read_recursive(&self) -> RwLockReadGuard<'_, R, T> {
         self.raw.lock_shared_recursive();
+        // SAFETY: The lock is held, as required.
         unsafe { self.read_guard() }
     }
 
@@ -547,7 +564,12 @@ impl<R: RawRwLockRecursive, T: ?Sized> RwLock<R, T> {
     /// This function does not block.
     #[inline]
     pub fn try_read_recursive(&self) -> Option<RwLockReadGuard<'_, R, T>> {
-        if self.raw.try_lock_shared_recursive() { Some(unsafe { self.read_guard() }) } else { None }
+        if self.raw.try_lock_shared_recursive() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.read_guard() })
+        } else {
+            None
+        }
     }
 }
 
@@ -568,6 +590,7 @@ impl<R: RawRwLockRecursiveTimed, T: ?Sized> RwLock<R, T> {
         timeout: R::Duration,
     ) -> Option<RwLockReadGuard<'_, R, T>> {
         if self.raw.try_lock_shared_recursive_for(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.read_guard() })
         } else {
             None
@@ -586,6 +609,7 @@ impl<R: RawRwLockRecursiveTimed, T: ?Sized> RwLock<R, T> {
         timeout: R::Instant,
     ) -> Option<RwLockReadGuard<'_, R, T>> {
         if self.raw.try_lock_shared_recursive_until(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.read_guard() })
         } else {
             None
@@ -614,6 +638,7 @@ impl<R: RawRwLockUpgrade, T: ?Sized> RwLock<R, T> {
     #[inline]
     pub fn upgradable_read(&self) -> RwLockUpgradableReadGuard<'_, R, T> {
         self.raw.lock_upgradable();
+        // SAFETY: The lock is held, as required.
         unsafe { self.upgradable_guard() }
     }
 
@@ -626,7 +651,12 @@ impl<R: RawRwLockUpgrade, T: ?Sized> RwLock<R, T> {
     /// This function does not block.
     #[inline]
     pub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<'_, R, T>> {
-        if self.raw.try_lock_upgradable() { Some(unsafe { self.upgradable_guard() }) } else { None }
+        if self.raw.try_lock_upgradable() {
+            // SAFETY: The lock is held, as required.
+            Some(unsafe { self.upgradable_guard() })
+        } else {
+            None
+        }
     }
 }
 
@@ -643,6 +673,7 @@ impl<R: RawRwLockUpgradeTimed, T: ?Sized> RwLock<R, T> {
         timeout: R::Duration,
     ) -> Option<RwLockUpgradableReadGuard<'_, R, T>> {
         if self.raw.try_lock_upgradable_for(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.upgradable_guard() })
         } else {
             None
@@ -661,6 +692,7 @@ impl<R: RawRwLockUpgradeTimed, T: ?Sized> RwLock<R, T> {
         timeout: R::Instant,
     ) -> Option<RwLockUpgradableReadGuard<'_, R, T>> {
         if self.raw.try_lock_upgradable_until(timeout) {
+            // SAFETY: The lock is held, as required.
             Some(unsafe { self.upgradable_guard() })
         } else {
             None