rust/pin-init/src/__internal.rs

Source file repositories/reference/linux-study-clean/rust/pin-init/src/__internal.rs

File Facts

System
Linux kernel
Corpus path
rust/pin-init/src/__internal.rs
Extension
.rs
Size
12245 bytes
Lines
405
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

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:?}");
}

// Marker types that determines type of `DropGuard`'s let bindings.
pub struct Pinned;
pub struct Unpinned;

/// Represent an uninitialized field.
///
/// # Invariants
///
/// - `ptr` is valid, properly aligned and points to uninitialized and exclusively accessed memory.
/// - If `P` is `Pinned`, then `ptr` is structurally pinned.
pub struct Slot<P, T: ?Sized> {
    ptr: *mut T,
    _phantom: PhantomData<P>,
}

impl<P, T: ?Sized> Slot<P, T> {
    /// # Safety
    ///
    /// - `ptr` is valid, properly aligned and points to uninitialized and exclusively accessed
    ///   memory.
    /// - If `P` is `Pinned`, then `ptr` is structurally pinned.
    #[inline(always)]
    pub unsafe fn new(ptr: *mut T) -> Self {
        // INVARIANT: Per safety requirement.
        Self {
            ptr,
            _phantom: PhantomData,
        }
    }

    /// Initialize the field by value.
    #[inline(always)]
    pub fn write(self, value: T) -> DropGuard<P, T>
    where
        T: Sized,
    {
        // SAFETY: `self.ptr` is a valid and aligned pointer for write.
        unsafe { self.ptr.write(value) }
        // SAFETY:
        // - `self.ptr` is valid and properly aligned per type invariant.
        // - `*self.ptr` is initialized above and the ownership is transferred to the guard.
        // - If `P` is `Pinned`, `self.ptr` is pinned.
        unsafe { DropGuard::new(self.ptr) }
    }
}

impl<T: ?Sized> Slot<Unpinned, T> {
    /// Initialize the field.
    #[inline(always)]
    pub fn init<E>(self, init: impl Init<T, E>) -> Result<DropGuard<Unpinned, T>, E> {
        // SAFETY:
        // - `self.ptr` is valid and properly aligned.
        // - when `Err` is returned, we also propagate the error without touching `slot`;
        //   also `self` is consumed so it cannot be touched further.
        unsafe { init.__init(self.ptr)? };

        // SAFETY:
        // - `self.ptr` is valid and properly aligned per type invariant.
        // - `*self.ptr` is initialized above and the ownership is transferred to the guard.
        Ok(unsafe { DropGuard::new(self.ptr) })
    }
}

impl<T: ?Sized> Slot<Pinned, T> {
    /// Initialize the field.
    #[inline(always)]
    pub fn init<E>(self, init: impl PinInit<T, E>) -> Result<DropGuard<Pinned, T>, E> {
        // SAFETY:
        // - `self.ptr` is valid and properly aligned.

Annotation

Implementation Notes