Skip to content

Commit

Permalink
Improve documentation for [A]Rc::into_inner
Browse files Browse the repository at this point in the history
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
1 parent d6b151f commit ab938b9
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 5 deletions.
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

0 comments on commit ab938b9

Please sign in to comment.