Commit 9b2299af authored by Benno Lossin's avatar Benno Lossin Committed by Miguel Ojeda
Browse files

rust: pin-init: add `std` and `alloc` support from the user-space version 



To synchronize the kernel's version of pin-init with the user-space
version, introduce support for `std` and `alloc`. While the kernel uses
neither, the user-space version has to support both. Thus include the
required `#[cfg]`s and additional code.

Signed-off-by: default avatarBenno Lossin <benno.lossin@proton.me>
Reviewed-by: default avatarFiona Behrens <me@kloenk.dev>
Tested-by: default avatarAndreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-17-benno.lossin@proton.me


[ Undo the temporary `--extern force:alloc` since now we have contents
  for `alloc` here. - Miguel ]
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent dbd5058b

rust/Makefile

+1 −1
Original line number Diff line number Diff line
@@ -121,7 +121,7 @@ rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE 


rustdoc-pin_init: private rustdoc_host = yes

rustdoc-pin_init: private rustc_target_flags = --extern pin_init_internal \

    --extern macros --extern force:alloc --cfg kernel --cfg feature=\"alloc\"

    --extern macros --extern alloc --cfg kernel --cfg feature=\"alloc\"

rustdoc-pin_init: $(src)/pin-init/src/lib.rs rustdoc-pin_init_internal \

    rustdoc-macros FORCE

	+$(call if_changed,rustdoc)

rust/pin-init/src/__internal.rs

+27 −0
Original line number Diff line number Diff line
@@ -189,6 +189,33 @@ pub fn init<E>(self: Pin<&mut Self>, init: impl PinInit<T, E>) -> Result<Pin<&mu 
    }

}



#[test]

fn stack_init_reuse() {

    use ::std::{borrow::ToOwned, println, string::String};

    use core::pin::pin;



    #[derive(Debug)]

    struct Foo {

        a: usize,

        b: String,

    }

    let mut slot: Pin<&mut StackInit<Foo>> = pin!(StackInit::uninit());

    let value: Result<Pin<&mut Foo>, core::convert::Infallible> =

        slot.as_mut().init(crate::init!(Foo {

            a: 42,

            b: "Hello".to_owned(),

        }));

    let value = value.unwrap();

    println!("{value:?}");

    let value: Result<Pin<&mut Foo>, core::convert::Infallible> =

        slot.as_mut().init(crate::init!(Foo {

            a: 24,

            b: "world!".to_owned(),

        }));

    let value = value.unwrap();

    println!("{value:?}");

}



/// When a value of this type is dropped, it drops a `T`.

///

/// Can be forgotten to prevent the drop.

rust/pin-init/src/alloc.rs

0 → 100644
+158 −0
Original line number Diff line number Diff line 
// SPDX-License-Identifier: Apache-2.0 OR MIT



#[cfg(all(feature = "alloc", not(feature = "std")))]

use alloc::{boxed::Box, sync::Arc};

#[cfg(feature = "alloc")]

use core::alloc::AllocError;

use core::{mem::MaybeUninit, pin::Pin};

#[cfg(feature = "std")]

use std::sync::Arc;



#[cfg(not(feature = "alloc"))]

type AllocError = core::convert::Infallible;



use crate::{

    init_from_closure, pin_init_from_closure, InPlaceWrite, Init, PinInit, ZeroableOption,

};



pub extern crate alloc;



// SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee).

//

// In this case we are allowed to use `T: ?Sized`, since all zeros is the `None` variant and there

// is no problem with a VTABLE pointer being null.

unsafe impl<T: ?Sized> ZeroableOption for Box<T> {}



/// Smart pointer that can initialize memory in-place.

pub trait InPlaceInit<T>: Sized {

    /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this

    /// type.

    ///

    /// If `T: !Unpin` it will not be able to move afterwards.

    fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>

    where

        E: From<AllocError>;



    /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this

    /// type.

    ///

    /// If `T: !Unpin` it will not be able to move afterwards.

    fn pin_init(init: impl PinInit<T>) -> Result<Pin<Self>, AllocError> {

        // SAFETY: We delegate to `init` and only change the error type.

        let init = unsafe {

            pin_init_from_closure(|slot| match init.__pinned_init(slot) {

                Ok(()) => Ok(()),

                Err(i) => match i {},

            })

        };

        Self::try_pin_init(init)

    }



    /// Use the given initializer to in-place initialize a `T`.

    fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>

    where

        E: From<AllocError>;



    /// Use the given initializer to in-place initialize a `T`.

    fn init(init: impl Init<T>) -> Result<Self, AllocError> {

        // SAFETY: We delegate to `init` and only change the error type.

        let init = unsafe {

            init_from_closure(|slot| match init.__init(slot) {

                Ok(()) => Ok(()),

                Err(i) => match i {},

            })

        };

        Self::try_init(init)

    }

}



#[cfg(feature = "alloc")]

macro_rules! try_new_uninit {

    ($type:ident) => {

        $type::try_new_uninit()?

    };

}

#[cfg(all(feature = "std", not(feature = "alloc")))]

macro_rules! try_new_uninit {

    ($type:ident) => {

        $type::new_uninit()

    };

}



impl<T> InPlaceInit<T> for Box<T> {

    #[inline]

    fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>

    where

        E: From<AllocError>,

    {

        try_new_uninit!(Box).write_pin_init(init)

    }



    #[inline]

    fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>

    where

        E: From<AllocError>,

    {

        try_new_uninit!(Box).write_init(init)

    }

}



impl<T> InPlaceInit<T> for Arc<T> {

    #[inline]

    fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>

    where

        E: From<AllocError>,

    {

        let mut this = try_new_uninit!(Arc);

        let Some(slot) = Arc::get_mut(&mut this) else {

            // SAFETY: the Arc has just been created and has no external references

            unsafe { core::hint::unreachable_unchecked() }

        };

        let slot = slot.as_mut_ptr();

        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,

        // slot is valid and will not be moved, because we pin it later.

        unsafe { init.__pinned_init(slot)? };

        // SAFETY: All fields have been initialized and this is the only `Arc` to that data.

        Ok(unsafe { Pin::new_unchecked(this.assume_init()) })

    }



    #[inline]

    fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>

    where

        E: From<AllocError>,

    {

        let mut this = try_new_uninit!(Arc);

        let Some(slot) = Arc::get_mut(&mut this) else {

            // SAFETY: the Arc has just been created and has no external references

            unsafe { core::hint::unreachable_unchecked() }

        };

        let slot = slot.as_mut_ptr();

        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,

        // slot is valid.

        unsafe { init.__init(slot)? };

        // SAFETY: All fields have been initialized.

        Ok(unsafe { this.assume_init() })

    }

}



impl<T> InPlaceWrite<T> for Box<MaybeUninit<T>> {

    type Initialized = Box<T>;



    fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {

        let slot = self.as_mut_ptr();

        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,

        // slot is valid.

        unsafe { init.__init(slot)? };

        // SAFETY: All fields have been initialized.

        Ok(unsafe { self.assume_init() })

    }



    fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {

        let slot = self.as_mut_ptr();

        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,

        // slot is valid and will not be moved, because we pin it later.

        unsafe { init.__pinned_init(slot)? };

        // SAFETY: All fields have been initialized.

        Ok(unsafe { self.assume_init() }.into())

    }

}

rust/pin-init/src/lib.rs

+35 −6
Original line number Diff line number Diff line
@@ -204,8 +204,16 @@ 
//! [structurally pinned fields]:

//!     https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field

//! [stack]: crate::stack_pin_init

//! [`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html

//! [`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html

#![cfg_attr(

    kernel,

    doc = "[`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html"

)]

#![cfg_attr(

    kernel,

    doc = "[`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html"

)]

#![cfg_attr(not(kernel), doc = "[`Arc<T>`]: alloc::alloc::sync::Arc")]

#![cfg_attr(not(kernel), doc = "[`Box<T>`]: alloc::alloc::boxed::Box")]

//! [`impl PinInit<Foo>`]: PinInit

//! [`impl PinInit<T, E>`]: PinInit

//! [`impl Init<T, E>`]: Init
@@ -239,6 +247,11 @@ 
#[doc(hidden)]

pub mod macros;



#[cfg(any(feature = "std", feature = "alloc"))]

mod alloc;

#[cfg(any(feature = "std", feature = "alloc"))]

pub use alloc::InPlaceInit;



/// Used to specify the pinning information of the fields of a struct.

///

/// This is somewhat similar in purpose as
@@ -914,8 +927,16 @@ macro_rules! assert_pinned { 
///     - `slot` is not partially initialized.

/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`.

///

/// [`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html

/// [`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html

#[cfg_attr(

    kernel,

    doc = "[`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html"

)]

#[cfg_attr(

    kernel,

    doc = "[`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html"

)]

#[cfg_attr(not(kernel), doc = "[`Arc<T>`]: alloc::alloc::sync::Arc")]

#[cfg_attr(not(kernel), doc = "[`Box<T>`]: alloc::alloc::boxed::Box")]

#[must_use = "An initializer must be used in order to create its value."]

pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {

    /// Initializes `slot`.
@@ -1005,8 +1026,16 @@ unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> { 
/// Contrary to its supertype [`PinInit<T, E>`] the caller is allowed to

/// move the pointee after initialization.

///

/// [`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html

/// [`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html

#[cfg_attr(

    kernel,

    doc = "[`Arc<T>`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html"

)]

#[cfg_attr(

    kernel,

    doc = "[`Box<T>`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html"

)]

#[cfg_attr(not(kernel), doc = "[`Arc<T>`]: alloc::alloc::sync::Arc")]

#[cfg_attr(not(kernel), doc = "[`Box<T>`]: alloc::alloc::boxed::Box")]

#[must_use = "An initializer must be used in order to create its value."]

pub unsafe trait Init<T: ?Sized, E = Infallible>: PinInit<T, E> {

    /// Initializes `slot`.