Rename DropGuard::into_inner to DropGuard::dismiss

[yoshuawuyts]

Tracking issue: #144426

One of the open questions blocking the stabilization of DropGuard is what to name the associated method that prevents the destructor from running, and returns the captured value. This method is currently called into_inner, but most people (including myself) feel like this would benefit from a method that calls more attention to itself.

This PR proposes naming this method dismiss, after the Linux kernel's ScopeGuard::dismiss. Which crucially does not evoke images of violence or weaponry the way alternatives such as "disarm" or "defuse" do. And personally I enjoy the visual metaphor of "dismissing a guard" (e.g. a person keeping watch over something) - a job well done, they're free to go.

This PR also changes the signature from an static method to an instance method. This also matches the Linux kernel's API, and seems alright since dismiss is not nearly as ubiquitous as into_inner. This makes it more convenient to use, with a much lower risk of conflicting. Though in the rare case there might be ambiguity, the explicit notation is available as a fallback.

let x = DropGuard::into_inner(guard);  // ← current
let x = guard.dismiss();               // ← proposed

[rustbot]

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

[hkBst]

Some alternative options (since I did not see any yet):

• unwrap
• yield
• leave
• give
• take
• release
• unguard
• deliver

[yoshuawuyts]

In the tracking issue, ACP, impl PR, and libs-api meeting the following options were brought up as well: disarm, defuse, disable, and skip_drop. Let me cover my thinking on all options here:

• disarm: references weaponry, and I'd rather we not.
• defuse: references explosives, same thing.
• disable: If we think of a "guard" as a person standing watch, "disabling" them reads pretty aggro.
• skip_drop: Is imo too verbose; I much prefer single verbs.
• unwrap: Will get us into trouble with DropGuard<Option<T>> if we make it an instance method.
• take: Same as unwrap.
• yield: Is a reserved keyword.
• give: Has the wrong polarity: if we take from the guard, we should give to the guard.

That leaves us with: dismiss, leave, release, unguard, and deliver. Out of these I still like dismiss best I think, but I'd be happy with release as well. For me it's a toss-up between those two.

[Mark-Simulacrum]

I assume libs-api nominated is appropriate?

[yoshuawuyts]

Yes, that's great - thank you!

[hkBst]

@yoshuawuyts If a guard guards a thing and you dismiss them, what happens with the thing? I guess it depends on how big/heavy the thing is. I think I like deliver and release because they align more with the imagery of the guard going away, but leaving the thing. With dismiss it sounds like the thing could be going away with the guard. In that light let me propose some more options:

• regain
• recover
• reclaim
• retain
• pass
• relinquish
• cede
• desert
• render
• surrender
• transfer
• provide
• dispense
• furnish
• disperse
• dispense
• succeed
• produce
• releave
• done