rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers

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

//! [`Opaque`]: kernel::types::Opaque

//! [`pin_data`]: ::macros::pin_data

//! [`UniqueArc<T>`]: kernel::sync::UniqueArc

use crate::{

    error::{self, Error},

    sync::UniqueArc,

};

use alloc::boxed::Box;

use core::{cell::Cell, convert::Infallible, marker::PhantomData, mem::MaybeUninit, ptr};

use core::{

    alloc::AllocError, cell::Cell, convert::Infallible, marker::PhantomData, mem::MaybeUninit,

    pin::Pin, ptr,

};

#[doc(hidden)]

pub mod __internal;

///

/// [`try_pin_init!`]: kernel::try_pin_init

/// [`NonNull<Self>`]: core::ptr::NonNull

/// [`Error`]: kernel::error::Error

// For a detailed example of how this macro works, see the module documentation of the hidden

// module `__internal` inside of `init/__internal.rs`.

#[macro_export]

///     }

/// }

/// ```

///

/// [`Error`]: kernel::error::Error

// For a detailed example of how this macro works, see the module documentation of the hidden

// module `__internal` inside of `init/__internal.rs`.

#[macro_export]

///

/// This initializer is for initializing data in-place that might later be moved. If you want to

/// pin-initialize, use [`pin_init!`].

///

/// [`Error`]: kernel::error::Error

// For a detailed example of how this macro works, see the module documentation of the hidden

// module `__internal` inside of `init/__internal.rs`.

#[macro_export]

///     }

/// }

/// ```

///

/// [`Error`]: kernel::error::Error

// For a detailed example of how this macro works, see the module documentation of the hidden

// module `__internal` inside of `init/__internal.rs`.

#[macro_export]

/// A pin-initializer for the type `T`.

///

/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can

/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`].

/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a

/// smart pointer like [`Arc<T>`] on this.

///

/// Also see the [module description](self).

///

///

/// [`Arc<T>`]: crate::sync::Arc

/// [`Arc::pin_init`]: crate::sync::Arc::pin_init

/// [`UniqueArc<T>`]: kernel::sync::UniqueArc

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

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

    /// Initializes `slot`.

/// An initializer for `T`.

///

/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can

/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can

/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart

/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can

/// use every function that takes it as well.

///

/// Also see the [module description](self).

/// move the pointee after initialization.

///

/// [`Arc<T>`]: crate::sync::Arc

/// [`UniqueArc<T>`]: kernel::sync::UniqueArc

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

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

    /// Initializes `slot`.

        Ok(())

    }

}

/// 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<E>(init: impl PinInit<T, E>) -> error::Result<Pin<Self>>

    where

        Error: From<E>,

    {

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

        let init = unsafe {

            pin_init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e)))

        };

        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<E>(init: impl Init<T, E>) -> error::Result<Self>

    where

        Error: From<E>,

    {

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

        let init = unsafe {

            init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e)))

        };

        Self::try_init(init)

    }

}

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>,

    {

        let mut this = Box::try_new_uninit()?;

        let slot = this.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 { this.assume_init() }.into())

    }

    #[inline]

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

    where

        E: From<AllocError>,

    {

        let mut this = Box::try_new_uninit()?;

        let slot = this.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> InPlaceInit<T> for UniqueArc<T> {

    #[inline]

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

    where

        E: From<AllocError>,

    {

        let mut this = UniqueArc::try_new_uninit()?;

        let slot = this.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 { this.assume_init() }.into())

    }

    #[inline]

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

    where

        E: From<AllocError>,

    {

        let mut this = UniqueArc::try_new_uninit()?;

        let slot = this.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() })

    }

}

use crate::{

    bindings,

    error::{self, Error},

    init::{InPlaceInit, Init, PinInit},

    types::{ForeignOwnable, Opaque},

};

use alloc::boxed::Box;

        // `Arc` object.

        Ok(unsafe { Self::from_inner(Box::leak(inner).into()) })

    }

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

    ///

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

    #[inline]

    pub fn pin_init<E>(init: impl PinInit<T, E>) -> error::Result<Self>

    where

        Error: From<E>,

    {

        UniqueArc::pin_init(init).map(|u| u.into())

    }

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

    ///

    /// This is equivalent to [`pin_init`], since an [`Arc`] is always pinned.

    #[inline]

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

    where

        Error: From<E>,

    {

        UniqueArc::init(init).map(|u| u.into())

    }

}

impl<T: ?Sized> Arc<T> {