Tracking Issue for `core::mem::DropGuard`

[yoshuawuyts]

View all comments

Feature gate: #![feature(drop_guard)]

This is a tracking issue for the core::mem::DropGuard API: a helper type that makes it easy to create impl Drop destructors inline.

Public API

/// Wrap a value and run a closure when dropped.
pub struct DropGuard<T, F: FnOnce(T)> { ... }

impl<T, F> DropGuard<T, F> {
    /// Create a new instance of `DropGuard`.
    pub fn new(inner: T, f: F) -> Self { ... }
    
    /// Consumes the `DropGuard`, returning the wrapped value.
    pub fn dismiss(guard: Self) -> T { ... }
}

impl<T, F> Deref for DropGuard<T, F> {
    type Target = T;
    fn deref(&self) -> &T { ... }
}
impl<T, F> DerefMut for DropGuard<T, F> { ... }
impl<T, F> Debug for DropGuard<T, F> { ... }
impl<T, F> Drop for DropGuard<T, F> { ... }

Example

#![feature(drop_guard)]

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!!!"
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: ACP: Add core::mem::WithDrop to associate a custom drop fn with some data libs-team#622
• Implementation: Add core::mem::DropGuard #144236
• Method name update: Rename DropGuard::into_inner to DropGuard::dismiss #148589 (comment)
• Use in various places in std: Use drop_guard in some places in {core,alloc,std} #161702
  • Reverted: Revert "Use drop_guard in some places in {core,alloc,std}" #162128
• Make the drop method #[inline]: Mark <mem::DropGuard as Drop>::drop as #[inline] #162064
• Final comment period (FCP)¹
• Stabilization PR Stabilize core::mem::DropGuard #161520

Unresolved Questions

• What should the name of the type be? DropGuard, WithDrop and Dropper were some of the preferred options raised in the 2025-07-22 T-Libs-API call.
• What should the name of the method be for "take ownership of the value without running the destructor"? The name current name for this method is into_inner, but other names have been proposed, including: disarm, defuse, disable, and skip_drop.
• Should the impl have a Clone impl? This can always be added in the future, but should be discussed further prior to stabilization.
• Should the Debug impl be transparent? This can always be added in the future, but should be discussed further prior to stabilization.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[RalfJung]

Another open question: what should into_inner be called? disarm might be a more evocative name.

[yoshuawuyts]

I've added it as an open question, and listed some of the other options people have brought up as well.

I should add however that I personally dislike any names that evoke imagery of weapons and violence. If we can at all avoid that, I think we should.

[RalfJung]

That is fair. I just think that into_inner has the significant downside of being a very common method name, so one could easily think one sees a call to something else -- or one could refactor code to change the type, and the into_inner may keep working while changing its meaning. I am fine with basically an name that's not a common method name found on many types. :)

[yoshuawuyts]

Yeah I agree: into_inner is a fairly inconspicuous name for an operation that is often load-bearing. Having something that more clearly calls attention to itself seems like it might be worth it.

[FeldrinH]

I just think that into_inner has the significant downside of being a very common method name, so one could easily think one sees a call to something else -- or one could refactor code to change the type, and the into_inner may keep working while changing its meaning.

I don't think this is a problem in practice. DropGaurd::into_inner is an associated function, not a method, so you have to call it as DropGuard::into_inner(value), which makes it quite hard to confuse it for some other into_inner function and also makes it a compile error to pass a value of a different type.

[FeldrinH]

FWIW I like the name into_inner. It is consistent with the existing scopeguard crate and also consistent with analogous methods on other types that affect drop behavior like ManuallyDrop and MaybeUninit.

[riking]

I think the documentation on into_inner should also have an example of calling mem::forget(guard.into_inner()) since mem::forget is mentioned in the prose.

[karolzwolak]

Implementation PR is merged, so @rustbot label -S-tracking-unimplemented

[tisonkun]

Upon dismiss naming, I wonder if we can avoid requiring pass in a value since a move || closure would already handle the ownership issue.

Then dismiss can even return ().

pub struct DropGuard<F = fn()>
where
    F: FnOnce(),
{
    f: ManuallyDrop<F>,
}

impl<F> DropGuard<F>
where
    F: FnOnce(),
{
    pub const fn new(f: F) -> Self {
        Self { f: ManuallyDrop::new(f) }
    }

    pub fn dismiss(guard: Self) -> () {
        let mut guard = ManuallyDrop::new(guard);
        unsafe { ManuallyDrop::drop(&mut guard.f) };
    }
}

impl<F> Drop for DropGuard<F>
where
    F: FnOnce(),
{
    fn drop(&mut self) {
        let f = unsafe { ManuallyDrop::take(&mut self.f) };
        f();
    }
}

In most cases, the pass-in value is (), and we'd seldom use Deref/DerefMut.

[tisonkun]

.. or have an ergonomic simple entry point when the value is ():

impl <F> DropGuard<(), F>
where
    F: FnOnce(()),
{
   pub const fn from_fn<FN: FnOnce()>(f: FN) -> Self {
        let f = move |()| f();
        Self::new((), f)
    }
}