Tracking issue for release notes of #161520: Stabilize `core::mem::DropGuard`

[rustbot]

This issue tracks the release notes text for #161520.

cc @yoshuawuyts, @nia-e -- original issue/PR authors and assignees for drafting text

See the forge.rust-lang.org chapter about release notes for an overview of how the release team makes use of these tracking issues.

Release notes text

This section should be edited to specify the correct category(s) for the change, with succinct description(s) of what changed. Some things worth considering:

• Does this need an additional compat notes section?
• Was this a libs stabilization that should have additional headers to list new APIs under Stabilized APIs and Const Stabilized APIs?

# Language/Compiler/Libraries/Stabilized APIs/Const Stabilized APIs/Rustdoc/Compatibility Notes/Internal Changes/Other
- [Stabilize `core::mem::DropGuard`](https://github.com/rust-lang/rust/pull/161520)

Tip

Use the previous releases for inspiration on how to write the release notes text and which categories to pick.

Release blog section

If this change is notable enough for inclusion in the blog post then this section should be edited to contain a draft for the blog post. Otherwise leave it empty.

### `DropGuard`: run a closure on every exit path

The `Drop` trait in Rust makes it possible to run code when a variable goes out of scope, regardless of whether we `return`, `?`, or panic. `Drop` being a part of types means that [in Rust you never have to close a socket](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/).

Implementing `Drop` can however feel a little inconvenient when all you want is to run some code unconditionally when a function exits. This is why we’re introducing `core::mem::DropGuard`: a new helper type that runs a closure when dropped.

`DropGuard` takes two arguments: a variable and a closure. It implements `Deref` and `DerefMut` so you can keep working with the variable as normal. But when dropped it runs the closure and consumes the variable.

`DropGuard` also implements a `dismiss` method which returns the variable from the guard without running the destructor. This makes it possible to quickly implement all-or-nothing transaction-like APIs with a rollback. Here is an example implementing a parser which uses a guard to roll back mutations in case of failure:

```rust
use std::mem::DropGuard;
use std::num::ParseIntError;

/// Attempt to parse all strings in `items` and push them into `nums`.
/// If parsing any of the strings fails, `nums` remains unchanged.
fn parse_all(nums: &mut Vec<u32>, strings: &[&str]) -> Result<(), ParseIntError> {
    let len = nums.len();
    let mut nums = DropGuard::new(nums, move |nums| {
        nums.truncate(len);    // ← 1. Reset the vec on failure
    });

    for s in strings {
        nums.push(s.parse()?); // ← 2. If `?` returns an error, roll back
    }

    DropGuard::dismiss(nums);  // ← 3. Parsing successful, dismiss the guard
    Ok(())
}
```

Note

If a blog post section is required the release-blog-post label should be added (@rustbot label +release-blog-post) to this issue as otherwise it may be missed by the release team.

[yoshuawuyts]

I wrote a snippet for the release blog section. I can't edit the comment above, so I'm pasting it here instead:

DropGuard: run a closure on every exit path

The Drop trait in Rust makes it possible to run code when a variable goes out of scope, regardless of whether we return, ?, or panic. Drop being a part of types means that in Rust you never have to close a socket.

Implementing Drop can however feel a little inconvenient when all you want is to run some code unconditionally when a function exits. This is why we’re introducing core::mem::DropGuard: a new helper type that runs a closure when dropped.

DropGuard takes two arguments: a variable and a closure. It implements Deref and DerefMut so you can keep working with the variable as normal. But when dropped it runs the closure and consumes the variable.

DropGuard also implements a dismiss method which returns the variable from the guard without running the destructor. This makes it possible to quickly implement all-or-nothing transaction-like APIs with a rollback. Here is an example implementing a parser which uses a guard to roll back mutations in case of failure:

use std::mem::DropGuard;
use std::num::ParseIntError;

/// Attempt to parse all strings in `items` and push them into `nums`.
/// If parsing any of the strings fails, `nums` remains unchanged.
fn parse_all(nums: &mut Vec<u32>, strings: &[&str]) -> Result<(), ParseIntError> {
    let len = nums.len();
    let mut nums = DropGuard::new(nums, move |nums| {
        nums.truncate(len);    // ← 1. Reset the vec on failure
    });

    for s in strings {
        nums.push(s.parse()?); // ← 2. If `?` returns an error, roll back
    }

    DropGuard::dismiss(nums);  // ← 3. Parsing successful, dismiss the guard
    Ok(())
}

[yoshuawuyts]

@rustbot label +release-blog-post

[nia-e]

yep, seems good! pasted it in ^^