Added minor clarification to specification of realloc.

[rust.git] / src / libcore / cell.rs

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index 4fcd0d9737d562252f7d82508e57e0beeba21e6e..e7eecf7540ad74121d4a0c840536afff154a98e5 100644 (file)
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -187,8 +187,6 @@
 //! ```
 //!
 
-// ignore-tidy-undocumented-unsafe
-
 #![stable(feature = "rust1", since = "1.0.0")]
 
 use crate::cmp::Ordering;
@@ -368,6 +366,10 @@ pub fn swap(&self, other: &Self) {
         if ptr::eq(self, other) {
             return;
         }
+        // SAFETY: This can be risky if called from separate threads, but `Cell`
+        // is `!Sync` so this won't happen. This also won't invalidate any
+        // pointers since `Cell` makes sure nothing else will be pointing into
+        // either of these `Cell`s.
         unsafe {
             ptr::swap(self.value.get(), other.value.get());
         }
@@ -387,6 +389,8 @@ pub fn swap(&self, other: &Self) {
     /// ```
     #[stable(feature = "move_cell", since = "1.17.0")]
     pub fn replace(&self, val: T) -> T {
+        // SAFETY: This can cause data races if called from a separate thread,
+        // but `Cell` is `!Sync` so this won't happen.
         mem::replace(unsafe { &mut *self.value.get() }, val)
     }
 
@@ -423,6 +427,8 @@ impl<T: Copy> Cell<T> {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get(&self) -> T {
+        // SAFETY: This can cause data races if called from a separate thread,
+        // but `Cell` is `!Sync` so this won't happen.
         unsafe { *self.value.get() }
     }
 
@@ -491,6 +497,9 @@ pub const fn as_ptr(&self) -> *mut T {
     #[inline]
     #[stable(feature = "cell_get_mut", since = "1.11.0")]
     pub fn get_mut(&mut self) -> &mut T {
+        // SAFETY: This can cause data races if called from a separate thread,
+        // but `Cell` is `!Sync` so this won't happen, and `&mut` guarantees
+        // unique access.
         unsafe { &mut *self.value.get() }
     }
 
@@ -510,6 +519,7 @@ pub fn get_mut(&mut self) -> &mut T {
     #[inline]
     #[stable(feature = "as_cell", since = "1.37.0")]
     pub fn from_mut(t: &mut T) -> &Cell<T> {
+        // SAFETY: `&mut` ensures unique access.
         unsafe { &*(t as *mut T as *const Cell<T>) }
     }
 }
@@ -553,6 +563,7 @@ impl<T> Cell<[T]> {
     /// ```
     #[stable(feature = "as_cell", since = "1.37.0")]
     pub fn as_slice_of_cells(&self) -> &[Cell<T>] {
+        // SAFETY: `Cell<T>` has the same memory layout as `T`.
         unsafe { &*(self as *const Cell<[T]> as *const [Cell<T>]) }
     }
 }
@@ -816,6 +827,8 @@ pub fn borrow(&self) -> Ref<'_, T> {
     #[inline]
     pub fn try_borrow(&self) -> Result<Ref<'_, T>, BorrowError> {
         match BorrowRef::new(&self.borrow) {
+            // SAFETY: `BorrowRef` ensures that there is only immutable access
+            // to the value while borrowed.
             Some(b) => Ok(Ref { value: unsafe { &*self.value.get() }, borrow: b }),
             None => Err(BorrowError { _private: () }),
         }
@@ -891,6 +904,7 @@ pub fn borrow_mut(&self) -> RefMut<'_, T> {
     #[inline]
     pub fn try_borrow_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError> {
         match BorrowRefMut::new(&self.borrow) {
+            // SAFETY: `BorrowRef` guarantees unique access.
             Some(b) => Ok(RefMut { value: unsafe { &mut *self.value.get() }, borrow: b }),
             None => Err(BorrowMutError { _private: () }),
         }
@@ -940,6 +954,7 @@ pub fn as_ptr(&self) -> *mut T {
     #[inline]
     #[stable(feature = "cell_get_mut", since = "1.11.0")]
     pub fn get_mut(&mut self) -> &mut T {
+        // SAFETY: `&mut` guarantees unique access.
         unsafe { &mut *self.value.get() }
     }