[lib] in-place initialization infrastructure

This is the initial design of the in-place initialization
interface, without the `PinInit` part.

Signed-off-by: Xiangfei Ding <[email protected]>
Co-authored-by: Benno Lossin <[email protected]>
Co-authored-by: Alice Ryhl <[email protected]>

Author: 3 people

compiler/rustc_hir/src/lang_items.rs

@@ -350,6 +350,11 @@ language_item_table! {
 
     MaybeUninit,             sym::maybe_uninit,        maybe_uninit,               Target::Union,          GenericRequirement::None;
 
+    Init,                    sym::init_trait,          init_trait,                 Target::Trait,          GenericRequirement::Exact(1);
+    InitError,               sym::init_error,          init_error,                 Target::AssocTy,        GenericRequirement::Exact(1);
+    InitLayout,              sym::init_layout,         init_layout,                Target::Method(MethodKind::Trait { body: false }), GenericRequirement::Exact(1);
+    InitInit,                sym::init_init,           init_init,                  Target::Method(MethodKind::Trait { body: false }), GenericRequirement::Exact(1);
+
     Termination,             sym::termination,         termination,                Target::Trait,          GenericRequirement::None;
 
     Try,                     sym::Try,                 try_trait,                  Target::Trait,          GenericRequirement::None;

compiler/rustc_span/src/symbol.rs

@@ -1200,6 +1200,11 @@ symbols! {
         infer_static_outlives_requirements,
         inherent_associated_types,
         inherit,
+        init,
+        init_error,
+        init_init,
+        init_layout,
+        init_trait,
         inlateout,
         inline,
         inline_const,

library/core/src/init.rs

@@ -0,0 +1,52 @@
+//! In-place initialization
+//!
+//! This module describes the interface through which types supporting in-place initialization
+//! interact with allocation mechanism to ensure correct and safe initialization of values
+//! within the memory slots provided by the allocation.
+
+use crate::ptr::Pointee;
+
+/// # Safety
+///
+/// Implementers must ensure that if `init` returns `Ok(metadata)`, then
+/// `core::ptr::from_raw_parts_mut(slot, metadata)` must reference a valid
+/// value owned by the caller. Furthermore, the layout returned by using
+/// `size_of` and `align_of` on this pointer must match what `Self::layout()`
+/// returns exactly.
+///
+/// Implementers must ensure that the implementation of `init()` does not rely
+/// on the value being pinned.
+#[unstable(feature = "in_place_initialization", issue = "999999")]
+#[lang = "init_trait"]
+pub unsafe trait Init<T: ?Sized + Pointee> {
+    /// Error type upon initialization failure during the actual
+    /// in-place initialization procedure.
+    #[lang = "init_error"]
+    type Error;
+
+    /// The layout needed by this initializer, which the allocation
+    /// should arrange the destination memory slot accordingly.
+    #[lang = "init_layout"]
+    fn layout(&self) -> crate::alloc::Layout;
+
+    /// Writes a valid value of type `T` to `slot` or fails.
+    ///
+    /// If this call returns [`Ok`], then `slot` is guaranteed to contain a valid
+    /// value of type `T`. If `T` is unsized, then `slot` may be combined with
+    /// the metadata to obtain a valid pointer to the value.
+    ///
+    /// Note that `slot` should be thought of as a `*mut T`. A unit type is used
+    /// so that the pointer is thin even if `T` is unsized.
+    ///
+    /// # Safety
+    ///
+    /// The caller must provide a pointer that references a location that `init`
+    /// may write to, and the location must have at least the size and alignment
+    /// specified by [`Init::layout`].
+    ///
+    /// If this call returns `Ok` and the initializer does not implement
+    /// `Init<T>`, then `slot` contains a pinned value, and the caller must
+    /// respect the usual pinning requirements for `slot`.
+    #[lang = "init_init"]
+    unsafe fn init(self, slot: *mut ()) -> Result<T::Metadata, Self::Error>;
+}

library/core/src/lib.rs

@@ -363,6 +363,10 @@ pub mod task;
 #[allow(missing_docs)]
 pub mod alloc;
 
+/* In-place initialization */
+#[unstable(feature = "in_place_initialization", issue = "999999")]
+pub mod init;
+
 // note: does not need to be public
 mod bool;
 mod escape;