Add `core::mem::DropGuard` #144236

yoshuawuyts · 2025-07-21T01:08:11Z

Note: The functionality added in this PR is now being tracked in #144426.

1.0 Summary

This PR introduces a new type core::mem::DropGuard which wraps a value and runs a closure when the value is dropped.

use core::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!!!"

2.0 Motivation

A number of programming languages include constructs like try..finally or defer to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the Drop trait instead, allowing us to never having to manually close sockets.

While Drop (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an impl Drop can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private DropGuard impls used internally:

3.0 Design

This PR implements what can be considered about the simplest possible design:

A single type DropGuard which takes both a generic type T and a closure F.
Deref + DerefMut impls to make it easy to work with the T in the guard.
An impl Drop on the guard which calls the closure F on drop.
An inherent fn into_inner which takes the type T out of the guard without calling the closure F.

Notably this design does not allow divergent behavior based on the type of drop that has occurred. The scopeguard crate includes additional on_success and on_onwind variants which can be used to branch on unwind behavior instead. However in a lot of cases this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality:

let guard = DropGuard::new((), |s| ...);  // 1. Arm the guard
other_function();                         // 2. Perform operations
guard.into_inner();                       // 3. Disarm the guard

DropGuard combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like hashbrown.

4.0 Acknowledgements

This implementation is based on the mini-scopeguard crate which in turn is based on the scopeguard crate. The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right!

5.0 Conclusion

This PR adds a new type core::mem::DropGuard to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the scopeguard crate into the stdlib, which is the 49th most downloaded crate on crates.io (387 million downloads).

Given the actual implementation of DropGuard is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!

rustbot · 2025-07-21T01:08:15Z

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

workingjubilee · 2025-07-21T01:10:45Z

this appears to be revisiting rust-lang/libs-team#622

yoshuawuyts · 2025-07-21T01:45:17Z

this appears to be revisiting rust-lang/libs-team#622

Oh you mean the naming? I guess I missed that issue since it's just a few days old. Most of the names come from the mini-scopeguard crate I put together in preparation for this PR earlier this year. To give some rationale for the names:

core::mem::DropGuard groups nicely with core::mem::drop and core::mem::ManuallyDrop. It would be the third drop-related operation we're putting in mem, and it's worth making it sound both similar yet distinctly identifiable.
core::mem::DropGuard functions very similarly to all the other guards we have in the stdlib. I think of the "guard" suffix as "does interesting things on drop", which checks out.
In the stdlib we've been using the name DropGuard for many years now, with at least 10 instances of it. That seems like pretty good precedent, and a decent indicator that the name is memorable.
The ScopeGuard crate uses the ScopeGuard::into_inner method to take a value without running the destructors. Its signature is also nearly identical to all the other into_inner methods we have.

This to me seemed like a reasonable starting point for a contribution. The part I'm least sure about is the into_inner method, since it does something interesting that might be worth calling attention to in a way that into_inner might not. Since this is only an initial impl, I'm not sure we should block on that though. Instead I think we should probably keep that as an open question?

orlp · 2025-07-21T08:35:02Z

Some things missing in this PR from my ACP (which makes sense since it was apparently done in parallel):

The function type in my ACP is defaulted to = fn(T):

pub struct WithDrop<T, F: FnOnce(T) = fn(T)> {

This is similar to how it is defaulted in LazyLock to make writing static declarations easier.

new is not marked const. There's no reason it shouldn't be.
new is not marked #[must_use]. This is important to prevent accidental instant-dropping.
Clone is not derived. I think this somewhat makes sense if you think of this type as exclusively a guard, but I think of this more generally, and under that umbrella there is no reason Clone shouldn't be derived.

There are also some differences:

The name of the type, I proposed WithDrop, but this is best discussed in the ACP, and I placed a comment there.
Debug is not implemented, but rather derived. This gives rather ugly results.
I intentionally did not implement PartialEq, Eq, PartialOrd, Ord, Hash, but this PR does (through derives). It's not clear to me that these traits should be implemented for this type as it's unclear whether these relationships include the on_drop function to compare or not. One user might expect equality to only include the payload, and another might expect it to include the function. As it's written right now it's also dangerous because Deref coercion might change equality results (since post-Deref only the value is compared, but pre-Deref both the value and function).

library/core/src/mem/drop_guard.rs

yoshuawuyts · 2025-07-21T14:27:45Z

Thanks @orlp, @purplesyringa, @bjorn3, @lukaslueg - you've raised some really good points. I'll try and address your comments either later today or tomorrow. But I wanted to take a moment to say thank you before then ^^

library/core/src/mem/drop_guard.rs

library/coretests/tests/mem.rs

library/core/src/mem/drop_guard.rs

yoshuawuyts · 2025-07-25T00:10:51Z

Filed a tracking issue in #144426, updated the #[unstable] attributes, and removed the = fn() -> T default parameter from the type. I never added the Clone impl to begin with, so I believe with that this PR should be in compliance with the T-Libs-API acceptance criteria defined in rust-lang/libs-team#622 (comment).

Once the latest CI run is green, I think this should be good to merge!

Mark-Simulacrum · 2025-07-27T23:11:35Z

r=me with commits squashed

yoshuawuyts · 2025-07-28T14:07:36Z

r=me with commits squashed

Squashed the commits, and CI is passing. I think we're good to merge!

Mark-Simulacrum · 2025-07-28T15:13:28Z

@bors r+

bors · 2025-07-28T15:13:33Z

📌 Commit 68f08c5 has been approved by Mark-Simulacrum

It is now in the queue for this repository.

…ulacrum Add `core::mem::DropGuard` ## 1.0 Summary This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped. ```rust use core::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!!!" ``` ## 2.0 Motivation A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/). While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally: - [library/alloc/src/vec/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/drain.rs#L177) - [library/alloc/src/boxed/thin.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/boxed/thin.rs#L362) - [library/alloc/src/slice.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/slice.rs#L413) - [library/alloc/src/collections/linked_list.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/linked_list.rs#L1135) - [library/alloc/src/collections/binary_heap/mod.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/binary_heap/mod.rs#L1816) - [library/alloc/src/collections/btree/map.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/btree/map.rs#L1715) - [library/alloc/src/collections/vec_deque/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/vec_deque/drain.rs#L95) - [library/alloc/src/vec/into_iter.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/into_iter.rs#L488) - [library/std/src/os/windows/process.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/std/src/os/windows/process.rs#L320) - [tests/ui/process/win-proc-thread-attributes.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/tests/ui/process/win-proc-thread-attributes.rs#L17) ## 3.0 Design This PR implements what can be considered about the simplest possible design: 1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`. 2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard. 3. An `impl Drop` on the guard which calls the closure `F` on drop. 4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`. Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](rust-lang#143612 (comment)) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality: ```rust let guard = DropGuard::new((), |s| ...); // 1. Arm the guard other_function(); // 2. Perform operations guard.into_inner(); // 3. Disarm the guard ``` `DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code). ## 4.0 Acknowledgements This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right! ## 5.0 Conclusion This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads). Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!

Rollup of 11 pull requests Successful merges: - #143289 (Remove `[T]::array_chunks(_mut)`) - #143883 (Add `--link-targets-dir` argument to linkchecker) - #144034 (tests: Test line number in debuginfo for diverging function calls) - #144236 (Add `core::mem::DropGuard`) - #144268 (Add method `find_ancestor_not_from_macro` and `find_ancestor_not_from_extern_macro` to supersede `find_oldest_ancestor_in_same_ctxt`) - #144303 (Consolidate staging for `rustc_private` tools) - #144539 (constify with_exposed_provenance) - #144569 (rustc-dev-guide subtree update) - #144573 (Raw Pointers are Constant PatKinds too) - #144578 (Ensure correct aligement of rustc_hir::Lifetime on platforms with lower default alignments.) - #144582 (fix `Atomic*::as_ptr` wording) r? `@ghost` `@rustbot` modify labels: rollup

…ulacrum Add `core::mem::DropGuard` ## 1.0 Summary This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped. ```rust use core::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!!!" ``` ## 2.0 Motivation A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/). While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally: - [library/alloc/src/vec/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/drain.rs#L177) - [library/alloc/src/boxed/thin.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/boxed/thin.rs#L362) - [library/alloc/src/slice.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/slice.rs#L413) - [library/alloc/src/collections/linked_list.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/linked_list.rs#L1135) - [library/alloc/src/collections/binary_heap/mod.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/binary_heap/mod.rs#L1816) - [library/alloc/src/collections/btree/map.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/btree/map.rs#L1715) - [library/alloc/src/collections/vec_deque/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/vec_deque/drain.rs#L95) - [library/alloc/src/vec/into_iter.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/into_iter.rs#L488) - [library/std/src/os/windows/process.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/std/src/os/windows/process.rs#L320) - [tests/ui/process/win-proc-thread-attributes.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/tests/ui/process/win-proc-thread-attributes.rs#L17) ## 3.0 Design This PR implements what can be considered about the simplest possible design: 1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`. 2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard. 3. An `impl Drop` on the guard which calls the closure `F` on drop. 4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`. Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](rust-lang#143612 (comment)) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality: ```rust let guard = DropGuard::new((), |s| ...); // 1. Arm the guard other_function(); // 2. Perform operations guard.into_inner(); // 3. Disarm the guard ``` `DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code). ## 4.0 Acknowledgements This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right! ## 5.0 Conclusion This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads). Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!

Rollup of 11 pull requests Successful merges: - #143883 (Add `--link-targets-dir` argument to linkchecker) - #144236 (Add `core::mem::DropGuard`) - #144303 (Consolidate staging for `rustc_private` tools) - #144367 (Move dist-apple-various from x86_64 to aarch64) - #144539 (constify with_exposed_provenance) - #144569 (rustc-dev-guide subtree update) - #144573 (Raw Pointers are Constant PatKinds too) - #144575 (fixed typo chunks->as_chunks) - #144578 (Ensure correct aligement of rustc_hir::Lifetime on platforms with lower default alignments.) - #144582 (fix `Atomic*::as_ptr` wording) - #144616 (coverage: Regression test for "function name is empty" bug) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 10 pull requests Successful merges: - #143883 (Add `--link-targets-dir` argument to linkchecker) - #144236 (Add `core::mem::DropGuard`) - #144367 (Move dist-apple-various from x86_64 to aarch64) - #144539 (constify with_exposed_provenance) - #144569 (rustc-dev-guide subtree update) - #144573 (Raw Pointers are Constant PatKinds too) - #144575 (fixed typo chunks->as_chunks) - #144578 (Ensure correct aligement of rustc_hir::Lifetime on platforms with lower default alignments.) - #144582 (fix `Atomic*::as_ptr` wording) - #144616 (coverage: Regression test for "function name is empty" bug) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #144236 - yoshuawuyts:drop-guard, r=Mark-Simulacrum Add `core::mem::DropGuard` ## 1.0 Summary This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped. ```rust use core::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!!!" ``` ## 2.0 Motivation A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/). While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally: - [library/alloc/src/vec/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/drain.rs#L177) - [library/alloc/src/boxed/thin.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/boxed/thin.rs#L362) - [library/alloc/src/slice.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/slice.rs#L413) - [library/alloc/src/collections/linked_list.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/linked_list.rs#L1135) - [library/alloc/src/collections/binary_heap/mod.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/binary_heap/mod.rs#L1816) - [library/alloc/src/collections/btree/map.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/btree/map.rs#L1715) - [library/alloc/src/collections/vec_deque/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/vec_deque/drain.rs#L95) - [library/alloc/src/vec/into_iter.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/into_iter.rs#L488) - [library/std/src/os/windows/process.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/std/src/os/windows/process.rs#L320) - [tests/ui/process/win-proc-thread-attributes.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/tests/ui/process/win-proc-thread-attributes.rs#L17) ## 3.0 Design This PR implements what can be considered about the simplest possible design: 1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`. 2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard. 3. An `impl Drop` on the guard which calls the closure `F` on drop. 4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`. Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](#143612 (comment)) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality: ```rust let guard = DropGuard::new((), |s| ...); // 1. Arm the guard other_function(); // 2. Perform operations guard.into_inner(); // 3. Disarm the guard ``` `DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code). ## 4.0 Acknowledgements This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right! ## 5.0 Conclusion This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads). Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!

Fix typo in `DropGuard` doc Follows-up rust-lang#144236 (I happened to see the typo yesterday but didn’t think it should delay the PR’s merge so I kept quiet, sorryyyyy).

Rollup merge of #144634 - lucaswerkmeister:patch-1, r=lqd Fix typo in `DropGuard` doc Follows-up #144236 (I happened to see the typo yesterday but didn’t think it should delay the PR’s merge so I kept quiet, sorryyyyy).

…ulacrum Add `core::mem::DropGuard` ## 1.0 Summary This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped. ```rust use core::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!!!" ``` ## 2.0 Motivation A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/). While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally: - [library/alloc/src/vec/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/drain.rs#L177) - [library/alloc/src/boxed/thin.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/boxed/thin.rs#L362) - [library/alloc/src/slice.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/slice.rs#L413) - [library/alloc/src/collections/linked_list.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/linked_list.rs#L1135) - [library/alloc/src/collections/binary_heap/mod.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/binary_heap/mod.rs#L1816) - [library/alloc/src/collections/btree/map.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/btree/map.rs#L1715) - [library/alloc/src/collections/vec_deque/drain.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/collections/vec_deque/drain.rs#L95) - [library/alloc/src/vec/into_iter.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/alloc/src/vec/into_iter.rs#L488) - [library/std/src/os/windows/process.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/library/std/src/os/windows/process.rs#L320) - [tests/ui/process/win-proc-thread-attributes.rs](https://github.com/rust-lang/rust/blob/9982d6462bedf1e793f7b2dbd655a4e57cdf67d4/tests/ui/process/win-proc-thread-attributes.rs#L17) ## 3.0 Design This PR implements what can be considered about the simplest possible design: 1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`. 2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard. 3. An `impl Drop` on the guard which calls the closure `F` on drop. 4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`. Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](rust-lang#143612 (comment)) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality: ```rust let guard = DropGuard::new((), |s| ...); // 1. Arm the guard other_function(); // 2. Perform operations guard.into_inner(); // 3. Disarm the guard ``` `DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code). ## 4.0 Acknowledgements This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right! ## 5.0 Conclusion This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads). Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!

Fix typo in `DropGuard` doc Follows-up rust-lang#144236 (I happened to see the typo yesterday but didn’t think it should delay the PR’s merge so I kept quiet, sorryyyyy).

Rollup of 10 pull requests Successful merges: - rust-lang/rust#143883 (Add `--link-targets-dir` argument to linkchecker) - rust-lang/rust#144236 (Add `core::mem::DropGuard`) - rust-lang/rust#144367 (Move dist-apple-various from x86_64 to aarch64) - rust-lang/rust#144539 (constify with_exposed_provenance) - rust-lang/rust#144569 (rustc-dev-guide subtree update) - rust-lang/rust#144573 (Raw Pointers are Constant PatKinds too) - rust-lang/rust#144575 (fixed typo chunks->as_chunks) - rust-lang/rust#144578 (Ensure correct aligement of rustc_hir::Lifetime on platforms with lower default alignments.) - rust-lang/rust#144582 (fix `Atomic*::as_ptr` wording) - rust-lang/rust#144616 (coverage: Regression test for "function name is empty" bug) r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned Mark-Simulacrum Jul 21, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jul 21, 2025

This comment has been minimized.

Sign in to view

yoshuawuyts mentioned this pull request Jul 21, 2025

ACP: Add core::mem::WithDrop to associate a custom drop fn with some data rust-lang/libs-team#622

Closed

jieyouxu added the S-waiting-on-ACP Status: PR has an ACP and is waiting for the ACP to complete. label Jul 21, 2025

This comment has been minimized.

Sign in to view

purplesyringa reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

purplesyringa reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

yoshuawuyts commented Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Show resolved Hide resolved

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

lukaslueg reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

bjorn3 reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

purplesyringa reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Show resolved Hide resolved

purplesyringa reviewed Jul 21, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

yoshuawuyts commented Jul 21, 2025

View reviewed changes

library/coretests/tests/mem.rs Show resolved Hide resolved

This comment has been minimized.

Sign in to view

PatchMixolydic reviewed Jul 24, 2025

View reviewed changes

library/core/src/mem/drop_guard.rs Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

yoshuawuyts mentioned this pull request Jul 25, 2025

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

Open

8 tasks

This comment has been minimized.

Sign in to view

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 28, 2025

samueltardieu mentioned this pull request Jul 28, 2025

Rollup of 11 pull requests #144611

Closed

Zalathar mentioned this pull request Jul 29, 2025

Rollup of 12 pull requests #144618

Closed

Zalathar mentioned this pull request Jul 29, 2025

Rollup of 12 pull requests #144619

Closed

Zalathar mentioned this pull request Jul 29, 2025

Rollup of 11 pull requests #144622

Closed

Zalathar mentioned this pull request Jul 29, 2025

Rollup of 10 pull requests #144624

Merged

bors merged commit ed7d6a9 into rust-lang:master Jul 29, 2025
10 checks passed

rustbot added this to the 1.90.0 milestone Jul 29, 2025

yoshuawuyts deleted the drop-guard branch July 29, 2025 10:06

This was referenced Jul 29, 2025

Replace defer in chainofcommand with core::mem::DropGuard from nightly metta-systems/vesper#314

Open

This crate is made obsolete by Rust nightly 2025-07-30 andrewhickman/defer#4

Open

lucaswerkmeister mentioned this pull request Jul 29, 2025

Fix typo in DropGuard doc #144634

Merged

kennykerr mentioned this pull request Jul 31, 2025

windows-core: Error handling for Free/Owned<T> microsoft/windows-rs#3682

Open

Add core::mem::DropGuard #144236

Add core::mem::DropGuard #144236

Uh oh!

Conversation

yoshuawuyts commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1.0 Summary

2.0 Motivation

3.0 Design

4.0 Acknowledgements

5.0 Conclusion

Uh oh!

rustbot commented Jul 21, 2025

Uh oh!

workingjubilee commented Jul 21, 2025

Uh oh!

This comment has been minimized.

yoshuawuyts commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

orlp commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yoshuawuyts commented Jul 21, 2025

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

This comment has been minimized.

Uh oh!

This comment has been minimized.

yoshuawuyts commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

Mark-Simulacrum commented Jul 27, 2025

Uh oh!

yoshuawuyts commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mark-Simulacrum commented Jul 28, 2025

Uh oh!

bors commented Jul 28, 2025

Uh oh!

Uh oh!

Uh oh!

Add `core::mem::DropGuard` #144236

Add `core::mem::DropGuard` #144236

yoshuawuyts commented Jul 21, 2025 •

edited

Loading

yoshuawuyts commented Jul 21, 2025 •

edited

Loading

orlp commented Jul 21, 2025 •

edited

Loading

yoshuawuyts commented Jul 25, 2025 •

edited

Loading

yoshuawuyts commented Jul 28, 2025 •

edited

Loading