rust: add RefReservation.

This allows a ref-counted object to be allocated but initialised later.
It is useful, for example, to allocate in one context (e.g., sleepable
context) and initialise in a different context (e.g., atomic context).

It is the last remaining feature before we can remove all usages of
`Arc<T>` from Binder.

Signed-off-by: Wedson Almeida Filho <[email protected]>

Author: wedsonaf

rust/kernel/sync/arc.rs

@@ -25,7 +25,7 @@ use core::{
     cell::UnsafeCell,
     convert::{AsRef, TryFrom},
     marker::{PhantomData, Unsize},
-    mem::ManuallyDrop,
+    mem::{ManuallyDrop, MaybeUninit},
     ops::Deref,
     pin::Pin,
     ptr::{self, NonNull},
@@ -107,8 +107,8 @@ impl<T> Ref<T> {
         // SAFETY: By the invariant, `RefInner` is pinned and `T` is also pinned.
         let pinned = unsafe { Pin::new_unchecked(&mut inner.as_mut().data) };
 
-        // INVARIANT: The only places where `&mut T` is available are here, which is explicitly
-        // pinned, and in `drop`. Both are compatible with the pin requirements.
+        // INVARIANT: The only places where `&mut T` is available are in constructors, which are
+        // explicitly pinned, and in `drop`. Both are compatible with the pin requirements.
         init(pinned);
 
         // SAFETY: We just created `inner` with a reference count of 1, which is owned by the new
@@ -343,3 +343,45 @@ impl<T: ?Sized> Deref for RefBorrow<T> {
         self.inner_ref.deref()
     }
 }
+
+/// An allocated but not yet initialised ref-counted object.
+pub struct RefReservation<T> {
+    mem: Ref<MaybeUninit<T>>,
+}
+
+impl<T> RefReservation<T> {
+    /// Allocates memory for a [`Ref<T>`] instance.
+    ///
+    /// The instance is not initialised yet.
+    pub fn try_new() -> Result<Self> {
+        Ok(Self {
+            mem: Ref::try_new(MaybeUninit::<T>::uninit())?,
+        })
+    }
+
+    /// Converts a reservation into a real ref-counted object by initialising it.
+    pub fn commit(self, data: T) -> Ref<T> {
+        let mut inner = ManuallyDrop::new(self).mem.ptr;
+        // SAFETY: `inner.data` is writable and properly aligned because it was allocated for a
+        // `MaybeUninit<T>`, which is compatible with `T`.
+        unsafe { inner.as_mut().data.as_mut_ptr().write(data) };
+        // SAFETY: The new `Ref` is taking over `inner` from `self.mem` (which won't be dropped).
+        unsafe { Ref::<T>::from_inner(inner.cast()) }
+    }
+
+    /// Converts a reservation into a real ref-counted object by initialising it with the given
+    /// value and callback.
+    ///
+    /// This is useful because it provides a mutable reference to `T` at its final location.
+    pub fn commit_and_init<U: FnOnce(Pin<&mut T>)>(self, data: T, init: U) -> Ref<T> {
+        let mut ret = self.commit(data);
+
+        // SAFETY: By the invariant, `RefInner` is pinned and `T` is also pinned.
+        let pinned = unsafe { Pin::new_unchecked(&mut ret.ptr.as_mut().data) };
+
+        // INVARIANT: The only places where `&mut T` is available are in constructors, which are
+        // explicitly pinned, and in `drop`. Both are compatible with the pin requirements.
+        init(pinned);
+        ret
+    }
+}

rust/kernel/sync/mod.rs

@@ -31,7 +31,7 @@ mod locked_by;
 mod mutex;
 mod spinlock;
 
-pub use arc::{Ref, RefBorrow};
+pub use arc::{Ref, RefBorrow, RefReservation};
 pub use condvar::CondVar;
 pub use guard::{Guard, Lock};
 pub use locked_by::LockedBy;