From b91bcd318153d2396ce9cc4e8e372b05f515b9e9 Mon Sep 17 00:00:00 2001
From: Nick Mertin <nickmertin@gmail.com>
Date: Sun, 12 May 2024 12:42:24 -0400
Subject: [PATCH] Rename forget to forget_elements and add safety comments

---
 src/base/array_storage.rs     |  2 +-
 src/base/default_allocator.rs |  6 +++---
 src/base/matrix_view.rs       |  2 +-
 src/base/storage.rs           |  4 ++--
 src/base/vec_storage.rs       | 18 ++++++++++++++----
 5 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/src/base/array_storage.rs b/src/base/array_storage.rs
index a74e65161..15405a6a2 100644
--- a/src/base/array_storage.rs
+++ b/src/base/array_storage.rs
@@ -132,7 +132,7 @@ where
     }
 
     #[inline]
-    fn forget(self) {
+    fn forget_elements(self) {
         // No additional cleanup required.
         std::mem::forget(self);
     }
diff --git a/src/base/default_allocator.rs b/src/base/default_allocator.rs
index 72dc5fd2e..30207968c 100644
--- a/src/base/default_allocator.rs
+++ b/src/base/default_allocator.rs
@@ -211,7 +211,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements, but ensure the buffer itself is cleaned up.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }
@@ -242,7 +242,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }
@@ -273,7 +273,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }
diff --git a/src/base/matrix_view.rs b/src/base/matrix_view.rs
index 7c9e0248a..68e5d978e 100644
--- a/src/base/matrix_view.rs
+++ b/src/base/matrix_view.rs
@@ -231,7 +231,7 @@ macro_rules! storage_impl(
             }
 
             #[inline]
-            fn forget(self) {
+            fn forget_elements(self) {
                 // No cleanup required.
             }
         }
diff --git a/src/base/storage.rs b/src/base/storage.rs
index 41392f5f7..708a14402 100644
--- a/src/base/storage.rs
+++ b/src/base/storage.rs
@@ -150,8 +150,8 @@ pub unsafe trait Storage<T: Scalar, R: Dim, C: Dim = U1>: RawStorage<T, R, C> {
     where
         DefaultAllocator: Allocator<R, C>;
 
-    /// Cleans up the storage without calling the destructors on the contained elements.
-    fn forget(self);
+    /// Drops the storage without calling the destructors on the contained elements.
+    fn forget_elements(self);
 }
 
 /// Trait implemented by matrix data storage that can provide a mutable access to its elements.
diff --git a/src/base/vec_storage.rs b/src/base/vec_storage.rs
index 6e31c1be8..f0a0593fa 100644
--- a/src/base/vec_storage.rs
+++ b/src/base/vec_storage.rs
@@ -283,8 +283,13 @@ where
     }
 
     #[inline]
-    fn forget(mut self) {
-        // Set length to 0 so element destructors are not called.
+    fn forget_elements(mut self) {
+        // SAFETY: setting the length to zero is always sound, as it does not
+        // cause any memory to be deemed initialized. If the previous length was
+        // non-zero, it is equivalent to using mem::forget to leak each element.
+        // Then, when this function returns, self.data is dropped, freeing the
+        // allocated memory, but the elements are not dropped because they are
+        // now considered uninitialized.
         unsafe { self.data.set_len(0) };
     }
 }
@@ -340,8 +345,13 @@ where
     }
 
     #[inline]
-    fn forget(mut self) {
-        // Set length to 0 so element destructors are not called.
+    fn forget_elements(mut self) {
+        // SAFETY: setting the length to zero is always sound, as it does not
+        // cause any memory to be deemed initialized. If the previous length was
+        // non-zero, it is equivalent to using mem::forget to leak each element.
+        // Then, when this function returns, self.data is dropped, freeing the
+        // allocated memory, but the elements are not dropped because they are
+        // now considered uninitialized.
         unsafe { self.data.set_len(0) };
     }
 }