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

[yoshuawuyts]

I like reclaim and recover as potential names as well; thanks for the suggestions. I feel like if we go over every single name in that list, we might be here for a while. Though the reason why I don't like deliver is because just like give, it feels like it has the wrong polarity. My personal shortlist for names I'd like the libs API team to consider is:

• dismiss: as in - "dismissing a guard from their guard duty"
• release: as in - "releasing a guard from their guard duty" or "releasing into our custody something that was previously guarded"
• recover: as in - "recover something previously guarded" or "recover from assuming a guarded stance"
• reclaim: as in - "reclaiming custody of something previously not held by us"

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting.

One of our goals in the naming was to not emphasize "getting the value back" the way that into_inner or recover or similar do; many uses of this will call it and not use the return value.

Given that, the main names we focused on were dismiss and unguard. Both had proponents in the meeting.

We ended up not getting a consensus around unguard. We were able to get a rough consensus around dismiss.

[yoshuawuyts]

We were able to get a rough consensus around dismiss.

That's great; thanks for discussing this in the meeting. This matches the Linux kernel API and is also what this PR has implemented. I believe this PR should now be good to merge!

[tisonkun]

Shall we merge this since the consensus has been achieved? I'm going to adopt this feature in our database project ¹ and would try to avoid further rename breakings.

Footnotes

1. https://github.com/scopedb/ ↩

[joshtriplett]

@bors r+ rollup

[bors]

📌 Commit a15c21e has been approved by joshtriplett

It is now in the queue for this repository.