Add core::mem::DropGuard

Author: yoshuawuyts

library/core/src/mem/drop_guard.rs

@@ -0,0 +1,169 @@
+use core::mem::ManuallyDrop;
+use core::ops::{Deref, DerefMut};
+use core::ptr;
+
+/// Wrap a value and run a closure when dropped.
+///
+/// This is useful for quickly creating desructors inline.
+///
+/// # Examples
+///
+/// ```rust
+/// # #![allow(unused)]
+/// use std::mem::DropGuard;
+///
+/// {
+///     // Create a new guard around a string that will
+///     // print its value when dropped.
+///     let s = String::from("Chashu likes tuna");
+///     let mut s = DropGuard::new(s, |s| println!("{s}"));
+///
+///     // Modify the string contained in the guard.
+///     s.push_str("!!!");
+///
+///     // The guard will be dropped here, printing:
+///     // "Chashu likes tuna!!!"
+/// }
+/// ```
+#[unstable(feature = "drop_guard", issue = "none")]
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct DropGuard<T, F>
+where
+    F: FnOnce(T),
+{
+    inner: ManuallyDrop<T>,
+    f: ManuallyDrop<F>,
+}
+
+impl<T, F> DropGuard<T, F>
+where
+    F: FnOnce(T),
+{
+    /// Create a new instance of `DropGuard`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # #![allow(unused)]
+    /// use std::mem::DropGuard;
+    ///
+    /// let value = String::from("Chashu likes tuna");
+    /// let guard = DropGuard::new(value, |s| println!("{s}"));
+    /// ```
+    #[unstable(feature = "drop_guard", issue = "none")]
+    pub fn new(inner: T, f: F) -> Self {
+        Self {
+            inner: ManuallyDrop::new(inner),
+            f: ManuallyDrop::new(f),
+        }
+    }
+
+    /// Consumes the `Guard`, returning the wrapped value.
+    ///
+    /// This will not execute the closure. This is implemented as a static
+    /// method to prevent any potential conflicts with any other methods called
+    /// `into_inner` from the `Deref` and `DerefMut` impls.
+    ///
+    /// It is typically preferred to call this function instead of `mem::forget`
+    /// because it will appropriately de-initialize the closure stored in the
+    /// `DropGuard` before returning the stored value.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # #![allow(unused)]
+    /// use std::mem::DropGuard;
+    ///
+    /// let value = String::from("Nori likes chicken");
+    /// let guard = DropGuard::new(value, |s| println!("{s}"));
+    /// assert_eq!(Guard::into_inner(guard), "Nori likes chicken");
+    /// ```
+    #[unstable(feature = "drop_guard", issue = "none")]
+    #[inline]
+    pub fn into_inner(guard: Self) -> T {
+        // Implementation note: this is the same approach that scopeguard takes.
+
+        // First we ensure that dropping the guard will not trigger
+        // its destructor
+        let mut guard = ManuallyDrop::new(guard);
+
+        // Next we manually read the stored value from the guard.
+        //
+        // SAFETY: this is safe because we've taken ownership of the guard.
+        let value = unsafe { ptr::read(&*guard.inner) };
+
+        // Finally we drop the stored closure. We do this *after* having read
+        // the value, so that even if the closure's `drop` function panics,
+        // unwinding still tries to drop the value.
+        //
+        // SAFETY: this is safe because we've taken ownership of the guard.
+        unsafe { ManuallyDrop::drop(&mut guard.f) };
+        value
+    }
+}
+
+#[unstable(feature = "drop_guard", issue = "none")]
+impl<T, F> Deref for DropGuard<T, F>
+where
+    F: FnOnce(T),
+{
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        &*self.inner
+    }
+}
+
+#[unstable(feature = "drop_guard", issue = "none")]
+impl<T, F> DerefMut for DropGuard<T, F>
+where
+    F: FnOnce(T),
+{
+    fn deref_mut(&mut self) -> &mut T {
+        &mut *self.inner
+    }
+}
+
+#[unstable(feature = "drop_guard", issue = "none")]
+impl<T, F> Drop for DropGuard<T, F>
+where
+    F: FnOnce(T),
+{
+    fn drop(&mut self) {
+        // SAFETY: we're taking the values out of the `ManuallyDrop` with
+        // the express intent of dropping them.
+        let inner = unsafe { ManuallyDrop::take(&mut self.inner) };
+        let f = unsafe { ManuallyDrop::take(&mut self.f) };
+        f(inner);
+    }
+}
+
+// tests copied from https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs.html#1-595
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::Cell;
+
+    #[test]
+    fn test_only_dropped_by_closure_when_run() {
+        let value_drops = Cell::new(0);
+        let value = DropGuard::new((), |()| value_drops.set(1 + value_drops.get()));
+        let closure_drops = Cell::new(0);
+        let guard = DropGuard::new(value, |_| closure_drops.set(1 + closure_drops.get()));
+        assert_eq!(value_drops.get(), 0);
+        assert_eq!(closure_drops.get(), 0);
+        drop(guard);
+        assert_eq!(value_drops.get(), 1);
+        assert_eq!(closure_drops.get(), 1);
+    }
+
+    #[test]
+    fn test_into_inner() {
+        let dropped = Cell::new(false);
+        let value = DropGuard::new(42, |_| dropped.set(true));
+        let guard = DropGuard::new(value, |_| dropped.set(true));
+        let inner = DropGuard::into_inner(guard);
+        assert_eq!(dropped.get(), false);
+        assert_eq!(*inner, 42);
+    }
+}

library/core/src/mem/mod.rs

@@ -21,6 +21,10 @@ mod transmutability;
 #[unstable(feature = "transmutability", issue = "99571")]
 pub use transmutability::{Assume, TransmuteFrom};
 
+mod drop_guard;
+#[unstable(feature = "drop_guard", issue = "none")]
+pub use drop_guard::DropGuard;
+
 // This one has to be a re-export (rather than wrapping the underlying intrinsic) so that we can do
 // the special magic "types have equal size" check at the call site.
 #[stable(feature = "rust1", since = "1.0.0")]

library/std/src/lib.rs

@@ -331,6 +331,7 @@
 #![feature(clone_to_uninit)]
 #![feature(core_intrinsics)]
 #![feature(core_io_borrowed_buf)]
+#![feature(drop_guard)]
 #![feature(duration_constants)]
 #![feature(error_generic_member_access)]
 #![feature(error_iter)]