ACP: std::rc::RcUninit for deferred initialization and await-safe cyclic construction

[kstrafe]

Proposal

Problem statement

Today, building reference-counted cyclic graphs in std with Rc is possible but constrained: Rc::new_cyclic requires completing the cycle inside a single closure, which prevents spanning await points and makes staged or multi‑phase initialization awkward. This pushes developers toward mutation‑heavy patterns (e.g., UniqueRc with post‑construction setters, Option/MaybeUninit fields, or RefCell) that are error‑prone, can accidentally form strong cycles, and impose runtime costs on every access. There is no standard, zero‑overhead facility to allocate an Rc once, thread Weak links where needed, and initialize exactly once later, while preserving Rc/Weak invariants without exposing unsafe internals.

Motivating examples or use cases

• Asynchronous cyclic construction: allocate nodes, pass Weak handles across await points to connect edges incrementally, then initialize once the graph is fully wired, which Rc::new_cyclic cannot express because it must close the cycle in a single closure.
• Long chain or DAG builds without deep recursion or mutation: construct long linked lists or multi‑stage graphs iteratively, avoiding stack growth and post‑allocation “setter” patterns that require Option/MaybeUninit/RefCell workarounds.
• Safer construction that prevents accidental strong cycles: by separating allocation from one‑shot initialization, there is no need to temporarily install Rc placeholders or later mutate fields, reducing the risk of creating Rc<RefCell<_>> cycles during setup.

Solution sketch

Introduce std::rc::RcUninit<T>, a deferred‑initialization handle that reserves Rc storage first and initializes it exactly once later, returning an Rc<T>.

• Type and placement

  • pub struct RcUninit<T> in std::rc.
  • Lives in std because Rc/Weak layout and invariants are opaque; a sound, zero‑overhead deferred‑init mechanism must integrate with those invariants, which cannot be reproduced in a crate without relying on unstable internals.

• Core API (sketch)

  • fn new() -> RcUninit<T>: allocate Rc backing without constructing T.
  • fn weak(&self) -> Weak<T>: produce a Weak<T> during the uninitialized phase to thread edges into other nodes before initialization.
  • fn init(self, value: T) -> Rc<T>: consume RcUninit to initialize exactly once and return Rc<T>; double‑init is prevented by the type, and dropping an uninitialized RcUninit runs no T destructor.

• Semantics

  • Weak before init: Weak::upgrade returns None before init, and Some(Rc<T>) after init while the allocation is alive.
  • Send/Sync: mirrors Rc (i.e., !Send/!Sync).

Alternatives

• Rc::new_cyclic

  • Works for simple cycles created entirely inside one closure, but cannot span await points or multi‑phase wiring, and can require awkward nesting to thread all edges at once.

• UniqueRc plus setters

  • Forces mutation‑based setup and field placeholders (Option, MaybeUninit, Weak) that add runtime overhead (unwrap/clone, upgrade) and complexity, and increases the risk of creating strong cycles inadvertently (e.g., Rc<RefCell<_>> used during setup).

• External crates

  • Cannot achieve the same safety and zero‑overhead because Rc/Weak internals are not public; any external approach would either reimplement a parallel RC or rely on unsafe knowledge of std internals, which defeats the purpose of a standard facility. This is the key reason the feature should live in std.
  • Crate rcuninit is one implementation but makes brittle assumptions about data layout in std.

Links and related work

• PR: Implement RcUninit (#112566) — Implement RcUninit (#112566) rust#140640
• RcUninit was discussed in
  Cyclic Arc and Rc Builder #90
  https://internals.rust-lang.org/t/an-alternative-to-rc-new-cyclic/22849/6
  Tracking Issue for UniqueRc/UniqueArc rust#112566

[the8472]

Would UniqueRc<MaybeUninit<T>> work? If not, how does RcUninit improve on it?

[programmerjake]

if this is accepted, can the same API be added for Arc?

[programmerjake]

Would UniqueRc<MaybeUninit<T>> work? If not, how does RcUninit improve on it?

how do you get a Weak<T> from UniqueRc<MaybeUninit<T>>? What happens to those Weak<T> if you just convert UniqueRc<MaybeUninit<T>> to Rc<MaybeUninit<T>>?

[the8472]

how do you get a Weak from UniqueRc<MaybeUninit>?

You'd get a Weak<MaybeUninit> via downgrade. Maybe that's not appropriate, but without usage examples I'm not sure how it's intended to be used.

[programmerjake]

the way I see it RcUninit is a more powerful replacement for Rc::new_cyclic, where you can construct data structures that point to themselves, but unlike RcUnique they don't require you to construct the datastructure with placeholder Weak<T> and replace them again later by mutating the datastructure. e.g.:

pub mod m {
    pub struct A {
        b: Weak<B>,
        v: Box<dyn Debug>,
    }

    impl A {
        // using Result here, assume I'm using some mechanism that won't be added to std like Rc::try_new_cyclic might
        pub fn new(b: Weak<B>, v: Box<impl Debug>) -> Result<Self, String> {
            if random() {
                return Err("A::new failed".into());
            }
            Ok(Self { b, v })
        }
    }

    pub struct B {
        a: Weak<A>,
        v: Box<dyn Debug>,
    }

    impl B {
        pub fn new(a: Weak<A>, v: Box<impl Debug>) -> Result<Self, String> {
            if random() {
                return Err("B::new failed".into());
            }
            Ok(Self { a, v })
        }
    }
}

pub fn make_a_b(a_v: Box<impl Debug>, b_v: Box<impl Debug>) -> Result<(Rc<m::A>, Rc<m::B>), String> {
    let rc_a = RcUninit::new();
    let rc_b = RcUninit::new();
    let a = m::A::new(rc_b.weak(), a_v)?;
    let b = m::B::new(rc_a.weak(), b_v)?;
    Ok((rc_a.init(a), rc_b.init(b)))
}

[programmerjake]

for API naming, I think using names from Rc<T> and Box<MaybeUninit<T>> for methods are better, so use downgrade instead of weak, and write instead of init

[kstrafe]

@programmerjake Since Box::write is an associated function and not a method, would it make more sense to give a name like write_once since we take self for RcUninit? That way it's distinguished at the call site that this is a one-time-use only. Or should we make RcUninit::write an associated function? For the latter question, since RcUninit has no Deref or core::ops::Receiver, I think we can have this be a method.

@the8472 does the example given by @programmerjake satisfy the use case you were after? If not I can make another.

[programmerjake]

Since Box::write is an associated function and not a method, would it make more sense to give a name like write_once since we take self for RcUninit?

Box::write is just an associated function because Box<T>: Receiver<Target = T>. I think write is still the best name even as a method, this is like MaybeUninit::write which you also usually only use once. Taking self by value is enough for people to know you can only use it once.

[programmerjake]

it did just occur to me that RcUninit::write should probably return UniqueRc rather than Rc

[moulins]

Why not have both RcUninit::write(self) -> Rc and RcUninit::write_unique(self) -> UniqueRc?
RcUninit -> Rc would probably be the most common case, and UniqueRc::into_rc(blah.write(...)) seems unnecessarily verbose.