Implement RcUninit (#112566)

[kstrafe]

RcUninit allows the user to construct cyclic data structures without using Rc::new_cyclic, which allows cyclic constructions across await points. It also allows you to create long linked lists without overflowing the stack.

This is an alternative to UniqueRc. While UniqueRc does allow for cyclic data structures to be created, it must be done by mutating the UniqueRc. Mutation is prone to creating reference cycles. Construction-only assignment of fields, without any mutation to "set" the struct afterwards cannot generate reference cycles. It's also more cumbersome to work with.

For instance, if we have objects A, B, and C, and we want these to connect as A => B => C -> A (=> being strong, -> being weak), then we must do something along the following lines.

    let mut a_uniq = UniqueRc::new(A::new());
    let a_weak = UniqueRc::downgrade(&a_uniq);

    let c = Rc::new(C::new(a_weak));
    let b = Rc::new(B::new(c));

    a_uniq.set_b(b);
    let a = a_uniq.into_rc();

To implement A::set_b, the field A::b must either be

• Option<Rc<B>>: Requiring unwrap/clone for each access.
• MaybeUninit<Rc<B>>: Requiring unsafe.
• Weak<B>: Requiring upgrade for every access.

The above also makes it easier to make mistakes in more complex programs where we don't have the full picture. It is not hard to change the above into Rc<RefCell<A>>, and then provide this pointer to C, which would cause a reference cycle to be created once a.borrow_mut().set_b(b) gets called.

On the other hand RcUninit doesn't have this problem, since initialization is deferred. The equivalent would look like the following.

    let a_uninit = RcUninit::new();
    let b_uninit = RcUninit::new();
    let c_uninit = RcUninit::new();

    let c = c_uninit.init(C::new(a_uninit.weak()));
    let b = b_uninit.init(B::new(c));
    let a = a_uninit.init(b);

This creates the structure (A => B => C -> A)

Tracking Issue

#112566

RcUninit was discussed in
rust-lang/libs-team#90
https://internals.rust-lang.org/t/an-alternative-to-rc-new-cyclic/22849/6
#112566

[rustbot]

r? @thomcc

rustbot has assigned @thomcc.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rust-log-analyzer]

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

info: removing rustup binaries
info: rustup is uninstalled
##[group]Image checksum input
mingw-check-tidy
# We use the ghcr base image because ghcr doesn't have a rate limit
# and the mingw-check-tidy job doesn't cache docker images in CI.
FROM ghcr.io/rust-lang/ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  g++ \
---

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#12 4.415   Downloading filelock-3.18.0-py3-none-any.whl (16 kB)
#12 4.438 Collecting distlib<1,>=0.3.7
#12 4.445   Downloading distlib-0.3.9-py2.py3-none-any.whl (468 kB)
#12 4.458      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 469.0/469.0 KB 42.9 MB/s eta 0:00:00
#12 4.497 Collecting platformdirs<5,>=3.9.1
#12 4.504   Downloading platformdirs-4.3.7-py3-none-any.whl (18 kB)
#12 4.588 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#12 4.774 Successfully installed distlib-0.3.9 filelock-3.18.0 platformdirs-4.3.7 virtualenv-20.30.0
#12 4.775 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#12 DONE 4.9s

#13 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#13 DONE 0.0s
---
DirectMap4k:      131008 kB
DirectMap2M:     7208960 kB
DirectMap1G:    11534336 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test            --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py,cpp
##[group]Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.05s
##[endgroup]
WARN: currently no CI rustc builds have rustc debug assertions enabled. Please either set `rust.debug-assertions` to `false` if you want to use download CI rustc or set `rust.download-rustc` to `false`.
[TIMING] core::build_steps::tool::LibcxxVersionTool { target: x86_64-unknown-linux-gnu } -- 0.222
---
fmt check
Diff in /checkout/library/alloc/src/rc.rs:4187:
         };
 
         let ptr = NonNull::new(ptr).unwrap();
-        unsafe { (*ptr.as_ptr()).weak.set(2); };
+        unsafe {
+            (*ptr.as_ptr()).weak.set(2);
+        };
 
-        Self {
-            ptr,
-            weak: Weak {
-                ptr,
-                alloc: Global,
-            },
-        }
+        Self { ptr, weak: Weak { ptr, alloc: Global } }
     }
 }
 
Diff in /checkout/library/alloc/src/rc.rs:4212:
         };
 
         let ptr = NonNull::new(ptr).unwrap();
-        unsafe { (*ptr.as_ptr()).weak.set(2); };
+        unsafe {
+            (*ptr.as_ptr()).weak.set(2);
+        };
 
-        Self {
-            ptr,
-            weak: Weak {
-                ptr,
-                alloc,
-            },
-        }
+        Self { ptr, weak: Weak { ptr, alloc } }
     }
 
     /// Get a weak reference.
Diff in /checkout/library/alloc/src/rc.rs:4241:
         let alloc = self.weak.alloc.clone();
         mem::forget(self);
 
-        Rc {
-            ptr,
-            phantom: PhantomData,
-            alloc,
-        }
+        Rc { ptr, phantom: PhantomData, alloc }
     }
 }
 
fmt: checked 5999 files
Build completed unsuccessfully in 0:01:19