Change:
As I in the i.r-l.o prerelease thread, the documentation of the new(ly stabilized) and method could really use some elaboration before the 1.60 release. I'm quite familiar with refcounting, strong/weak refs, etc. but just from the doc, I have no idea what problem the new method solves exactly, when I should use it, why the closure is needed, how the closure argument seems to come from "thin air", and what the closure should return.
Argh, thanks. Could've sworn I specifically double-checked that I wrote "cyclic"…
Problem the method solves: constructing a which holds a pointer to itself. When you should use it: when you need to do the above. Previously you'd construct with e.g. and then mutate the value (via e.g. ) to fix up the self references. Where the closure argument comes from: essentially, the point of is that the place is allocated first, with strong=0, weak=1. The place has no data yet (you're constructing the value to place there), but is in the "zombie" state where it has weak references but no data. Why the closure is needed: the place needs to be "finished" once the value is created. In theory, you could "recover" any zombie weak, but for the most case, Rust wants to pretend that a "zombie" and a dangling are equivalent. What the closure should return: the closure returns the object to place in the reference counted place. After you've constructed the object, the reference count is "activated" and the object is accessable by (clones of) the weak pointer given to the constructor closure. For the most part, exists to construct style objects more easily, which is what the example demonstrates. It can be used for other use cases, but this is the primary motivating example. I'm biased because I know what is used for, so the existing documentation is enough. The docs aren't going to be changed for 1.60, but if you (or anyone) can improve the docs (with the above information or otherwise), PRs to do so are welcome!
I agree I had to read the documentation a few times to understand what this does.
Hi! Just a quick note that changing the documentation for the Rust 1.60.0 release itself will likely not be possible, that'd require a full release rebuild.
I'm sending a PR with explanations provided by so that it'll at least be in the next release. Why do you need a full release rebuild btw? Isn't it possible to regen the docs without rebuilding everything like the option on rustc?
I opened Feedback is very welcome. :)
Our release tooling only supports building everything at the same time.
Well, at least it'll be present in the next release with a beta backport.

Discussion:
} } <del> /// Constructs a new `Rc<T>` using a closure `data_fn` that has access to a /// weak reference to the constructing `Rc<T>`. </del> <ins> /// Constructs a new `Rc<T>` while giving you a `Weak<T>` to the allocation, /// to allow you to construct a `T` which holds a weak pointer to itself. </ins> /// /// Generally, a structure circularly referencing itself, either directly or <del> /// indirectly, should not hold a strong reference to prevent a memory leak. /// In `data_fn`, initialization of `T` can make use of the weak reference /// by cloning and storing it inside `T` for use at a later time. </del> <ins> /// indirectly, should not hold a strong reference to itself to prevent a memory leak. /// Using this function, you get access to the weak pointer during the /// initialization of `T`, before the `Rc<T>` is created, such that you can /// clone and store it inside the `T`. /// /// `new_cyclic` first allocates the managed allocation for the `Rc<T>`, /// then calls your closure, giving it a `Weak<T>` to this allocation, /// and only afterwards completes the construction of the `Rc<T>` by placing /// the `T` returned from your closure into the allocation. </ins> /// /// Since the new `Rc<T>` is not fully-constructed until `Rc<T>::new_cyclic` <del> /// returns, calling [`upgrade`] on the weak reference inside `data_fn` will </del> <ins> /// returns, calling [`upgrade`] on the weak reference inside your closure will </ins> /// fail and result in a `None` value. /// /// # Panics <ins> /// </ins> /// If `data_fn` panics, the panic is propagated to the caller, and the /// temporary [`Weak<T>`] is dropped normally. ///

/// impl Gadget { ///     /// Construct a reference counted Gadget. ///     fn new() -> Rc<Self> { <del> ///         Rc::new_cyclic(|me| Gadget { me: me.clone() }) </del> <ins> ///         // `me` is a `Weak<Gadget>` pointing at the new allocation of the ///         // `Rc` we're constructing. ///         Rc::new_cyclic(|me| { ///             // Create the actual struct here. ///             Gadget { me: me.clone() } ///         }) </ins> ///     } /// ///     /// Return a reference counted pointer to Self.

unsafe { Self::from_inner(Box::leak(x).into()) } } <del> /// Constructs a new `Arc<T>` using a closure `data_fn` that has access to /// a weak reference to the constructing `Arc<T>`. </del> <ins> /// Constructs a new `Arc<T>` while giving you a `Weak<T>` to the allocation, /// to allow you to construct a `T` which holds a weak pointer to itself. </ins> /// /// Generally, a structure circularly referencing itself, either directly or <del> /// indirectly, should not hold a strong reference to prevent a memory leak. /// In `data_fn`, initialization of `T` can make use of the weak reference /// by cloning and storing it inside `T` for use at a later time. </del> <ins> /// indirectly, should not hold a strong reference to itself to prevent a memory leak. /// Using this function, you get access to the weak pointer during the /// initialization of `T`, before the `Arc<T>` is created, such that you can /// clone and store it inside the `T`. </ins> /// <del> /// Since the new `Arc<T>` is not fully-constructed until /// `Arc<T>::new_cyclic` returns, calling [`upgrade`] on the weak /// reference inside `data_fn` will fail and result in a `None` value. </del> <ins> /// `new_cyclic` first allocates the managed allocation for the `Arc<T>`, /// then calls your closure, giving it a `Weak<T>` to this allocation, /// and only afterwards completes the construction of the `Arc<T>` by placing /// the `T` returned from your closure into the allocation. /// /// Since the new `Arc<T>` is not fully-constructed until `Arc<T>::new_cyclic` /// returns, calling [`upgrade`] on the weak reference inside your closure will /// fail and result in a `None` value. </ins> /// /// # Panics <ins> /// </ins> /// If `data_fn` panics, the panic is propagated to the caller, and the /// temporary [`Weak<T>`] is dropped normally. /// /// # Example <ins> /// </ins> /// ``` /// #![allow(dead_code)] /// use std::sync::{Arc, Weak};

/// impl Gadget { ///     /// Construct a reference counted Gadget. ///     fn new() -> Arc<Self> { <del> ///         Arc::new_cyclic(|me| Gadget { me: me.clone() }) </del> <ins> ///         // `me` is a `Weak<Gadget>` pointing at the new allocation of the ///         // `Arc` we're constructing. ///         Arc::new_cyclic(|me| { ///             // Create the actual struct here. ///             Gadget { me: me.clone() } ///         }) </ins> ///     } /// ///     /// Return a reference counted pointer to Self.