Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for [A]Rc::into_inner #120266

Merged
merged 1 commit into from
Jan 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Improve documentation for [A]Rc::into_inner
General improvements, and also aims to better encourage the reader
to actually check out Arc::try_unwrap.
  • Loading branch information
steffahn committed Jan 23, 2024
commit ab938b9acbf1d5849198cba19e14959d8ad2871f
7 changes: 5 additions & 2 deletions library/alloc/src/rc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -938,8 +938,11 @@ impl<T, A: Allocator> Rc<T, A> {
/// it is guaranteed that exactly one of the calls returns the inner value.
/// This means in particular that the inner value is not dropped.
///
/// This is equivalent to `Rc::try_unwrap(this).ok()`. (Note that these are not equivalent for
/// [`Arc`](crate::sync::Arc), due to race conditions that do not apply to `Rc`.)
/// [`Rc::try_unwrap`] is conceptually similar to `Rc::into_inner`.
/// And while they are meant for different use-cases, `Rc::into_inner(this)`
/// is in fact equivalent to <code>[Rc::try_unwrap]\(this).[ok][Result::ok]()</code>.
/// (Note that the same kind of equivalence does **not** hold true for
/// [`Arc`](crate::sync::Arc), due to race conditions that do not apply to `Rc`!)
#[inline]
#[stable(feature = "rc_into_inner", since = "1.70.0")]
pub fn into_inner(this: Self) -> Option<T> {
Expand Down
10 changes: 7 additions & 3 deletions library/alloc/src/sync.rs
Original file line number Diff line number Diff line change
Expand Up @@ -983,9 +983,13 @@ impl<T, A: Allocator> Arc<T, A> {
/// it is guaranteed that exactly one of the calls returns the inner value.
/// This means in particular that the inner value is not dropped.
///
/// 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`].
/// [`Arc::try_unwrap`] is conceptually similar to `Arc::into_inner`, but it
/// is meant for different use-cases. If used as a direct replacement
/// for `Arc::into_inner` anyway, such as with the expression
/// <code>[Arc::try_unwrap]\(this).[ok][Result::ok]()</code>, then it does
/// **not** give the same guarantee as described in the previous paragraph.
/// For more information, see the examples below and read the documentation
/// of [`Arc::try_unwrap`].
///
/// # Examples
///
Expand Down
Loading