Tracking Issue for {Arc, Rc}::into_inner

[steffahn]

Feature gates: #![feature(arc_into_inner)], #![feature(rc_into_inner)]

This is a tracking issue for the Arc::into_inner method, and (for API-consistency) also an Rc::into_inner analogue.

The function Arc::into_inner(x) serves as an atomic race-condition-free alternative to Arc::try_unwrap(x).ok(). See the ACP for more details.

Public API

// alloc::sync

impl<T> Arc<T> {
    /// Returns the inner value, if the `Arc` has exactly one strong reference.
    /// Otherwise, `None` is returned and the `Arc` is dropped.
    pub fn into_inner(this: Arc<T>) -> Option<T>;
}

and the extension to Rc

// alloc::rc

impl<T> Rc<T> {
    /// Returns the inner value, if the `Rc` has exactly one strong reference.
    /// Otherwise, `None` is returned and the `Rc` is dropped.
    pub fn into_inner(this: Rc<T>) -> Option<T>;
}

Steps / History

• ACP: Add Arc::into_inner for safely discarding Arcs without calling the destructor on the inner type. libs-team#162
• Implementation:
  • Arc::into_inner Add Arc::into_inner for safely discarding Arcs without calling the destructor on the inner type. #106854
  • Rc::into_inner Introduce Rc::into_inner, as a parallel to Arc::into_inner #109026
• Final comment period (FCP)¹
• Stabilization PR: Stabilize arc_into_inner and rc_into_inner. #109504

Unresolved Questions

• None yet.

Footnotes

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

[ryoqun]

Hey, I've stumbled on this. I wonder how soon this can be stabilized? My usecase is complex. but in a nut shell, I want this to conditionally and cleanly restart bunch of interconnected threads of mixed roles, all sharing Arc<GlobalContext>, depending on which thread did actually dropped the GlobalContext.

if sharing helps, i can write the usecase in detail...

Of course, I can resort to sync::Weak or tls. but it incurs overhead and/or further complexities. or mem::transmute like this to forcibly bring ::into_inner into stable rustc: https://rust.godbolt.org/z/r5rbsYYcT, in which i have to use unsafe... Also, due to already-existing wide-spread use of Arc<GlobalContext> in our codebase, switching to different Arc impl altogether isn't viable as well. That precondition also precludes more saner cleaning code arrangement in the first place. ;)

[joshtriplett]

Submitted the Rc::into_inner implementation as #109026

[joshtriplett]

I think Arc::into_inner makes sense to stabilize at this point. And Rc::into_inner is trivial.

@rust-lang/libs-api, shall we stabilize these?

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[steffahn]

@thynson Feel free to open an issue if you have concrete ideas how the documentation of Arc::into_inner can be improved to convince users to actually look at the Arc::try_unwrap function. Of course, it's already mentioned there multiple times (it's also mentioned on this tracking issue) but apparently not in a way that convinced you to actually look at that method.

Maybe also a doc alias “try_into_inner” for try_unwrap to further help discoverability 🤔 (though I'm not sure off the top of my head, how well those work for associated items; and also that would assume people use the search bar, anyways)

[thynson]

Umm, it's my bad that Arc::try_unwrap already mentioned in the doc of Arc::into_inner, which is exactly what I'm looking for, through the doc make me feel it's discouraged to be used

    /// ...
    ///
    /// The similar expression `Arc::try_unwrap(this).ok()` does not
    /// offer such a guarantee. See the last example below
    /// and the documentation of [`Arc::try_unwrap`].
    ///
    /// ...

Actually they're designed for different scenarios. Probably better to document it like:

    /// ...
    ///
    /// `Arc::try_unwrap` offers similar functionality but it's designed 
    /// for difference scenarios, while this function is suitable for dropping
    /// a clone of an `Arc`, obtaining the wrapped `T` when the last clone of an
    ///  `Arc` was dropped.
    ///
    /// ...

[steffahn]

Hmm, no try_unwrap is only meant to be discouraged in the case where you ignore the Arc<T> you get back in the Err case. That’s clearly documented, too… but it’s describing the details of when and how to use try_unwrap, and hence not documented in into_inner’s documentation.

On the other hand, I wasn’t aware that someone could try to combine into_inner with a Arc::strong_count(…) == 1 check.

Anyways… maybe a sentence that introduces Arc::try_unwrap before immediately calling out an expression using it could be sufficiently useful, after all.

If Arc::into_inner is called on every clone of this Arc, it is guaranteed that exactly one of the calls returns the inner value. This means in particular that the inner value is not dropped.

Arc::try_unwrap offers similar functionality to this function, and might seem simply like a more general/powerful API than Arc::into_inner; but it has in fact different use-cases. It you did use it to replace Arc::into_inner, such as with the expression Arc::try_unwrap(this).ok(), then you would not get the guarantee described in the previous paragraph. For more information, see the last example below and read the documentation of Arc::try_unwrap.

^^^ Maybe like this?

[thynson]

It you did use it to replace Arc::into_inner, ...

If I understand it right, it looks like a typos of

If you did use it to replace Arc::into_inner, ...

The modified version should be clear enough for me.
And thanks for your quick response. 🥇

[steffahn]

@thynson I’ve changed the wording a bit more, feel free to take a look #120266