Tracking Issue for core::mem::DropGuard

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.

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

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

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.

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. :)

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.

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.

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.

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.

@rustbot

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

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.

.. 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)
    }
}

@ais523

Regarding naming¹, .dismantle() might be what I've found most befitting. Indeed it is a word which conveys both:

the deäctivation/disabling (or using pre-existing terminology in third-party crates, defusing/disarming) of the drop glue;
the .into_inner() deconstruction that it results into.

And it is not itself weaponry-related (you can dismantle an operation, for instance).

@ais523 Regarding the drop glue, I think that an API along the lines of https://docs.rs/safe-manually-drop would fit it better, insofar the drop logic would be written as an impl rather than as a closure inside the constructor. Though perhaps we could unify both ideas by using a proxy trait for the second type parameter of the DropGuard, like this:

pub struct DropGuard<T, F>(
    MD<T>,
    MD<F>,
)
where
    F: DropManually<T>,
;

pub trait DropManually<T> {
    fn drop_manually(self, field: T);
}

impl<F: FnOnce(T), T> DropManually<T> for F {
    fn drop_manually(self, field: T) {
        self(field)
    }
}

impl<T, F: DropManually<T>> Drop for DropGuard<T, F> {
    fn drop(&mut self) {
        F::drop_manually(
            unsafe { MD::take(&mut self.1) },
            unsafe { MD::take(&mut self.0) },
        )
    }
}

This would retain compatibility with the current API, but would also allow your use-case, @ais523:

Click to see

pub struct CellGuard<'a, T>(
    DropGuard<CellGuardFields<'a, T>, PD<Self>>,
);
// where:
struct CellGuardFields<'a, T> {
    cell: &'a Cell<Option<T>>,
    val: T
}

impl<'a, T> DropManually<CellGuardFields<'a, T>> for PD<CellGuard<'a, T>> {
    fn drop_manually(self, CellGuardFields { cell, val }: CellGuardFields<'a, T>) {
        cell.set(Some(val))
    }
}

Playground

which makes the drop glue stand out more (à la impl Drop), than in:

pub struct CellGuard<'a, T>(
    DropGuard<CellGuardFields<'a, T>, CellGuardDestructor<'a, T>>,
);
// where
struct CellGuardFields<'a, T> {
    cell: &'a Cell<Option<T>>,
    val: T
}

type CellGuardDestructor<'a, T> = impl FnOnce(CellGuardFields<'a, T>);

impl<'a, T> CellGuard<'a, T> {
    #[define_opaque(CellGuardDestructor)]
    pub fn new(o: &'a Cell<Option<T>>) -> Self {
        CellGuard(DropGuard::new(
            CellGuardFields {
                cell: o,
                val: o.take().unwrap()
            },
            |cgf| cgf.cell.set(Some(cgf.val))))
    }

Though after writing all this I am starting to think there may be more clarity in having both SafeManuallyDrop and DropGuard than trying to shoehorn the two together, since I am not 100% fond of the PD<…> layer with DropGuard (and also, the "non-entailed FnOnce" would probably hamper closure arg inference in the more typical DropGuard intended case of the OP).

(as I have not seen any explicit mentions/considerations in the latest minutes of the candidate names suggested on Zulip) ↩

Rollup merge of rust-lang#161702 - GrigorenkoPV:drop-guard, r=clarfon…

Unrolled build for #161702 in rollup 162028

Rollup merge of rust-lang#161520 - yoshuawuyts:stabilize-dropguard, r…

Unrolled build for #161520 in rollup 162707

Rollup merge of rust-lang#164414 - theemathas:let_underscore_drop_gua…

Navigation Menu

Repository navigation

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

Public API

Example

Steps / History

Unresolved Questions

32 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for core::mem::DropGuard #144426

Description

Public API

Example

Steps / History

Unresolved Questions

Footnotes

Activity

RalfJung commented on Jul 28, 2025

yoshuawuyts commented on Jul 28, 2025

RalfJung commented on Jul 28, 2025

yoshuawuyts commented on Jul 28, 2025

FeldrinH commented on Jul 31, 2025

FeldrinH commented on Jul 31, 2025

riking commented on Aug 15, 2025

karolzwolak commented on Aug 24, 2025

tisonkun commented on Nov 25, 2025

tisonkun commented on Nov 25, 2025

32 remaining items

danielhenrymantilla commented on Aug 22, 2026

Footnotes

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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