Struct pinned_init::needs_init::NeedsPinnedInit

#[repr(transparent)]
pub struct NeedsPinnedInit<'init, T: PinnedInit> { /* private fields */ }

A pointer to pinned data that needs to be initialized while pinned. When this pointer is neglected and not initialized, it will

• panic on drop (when debug assertions are enabled)
• produce a link time error (when debug assertions are disabled) This is to prevent partial initialization and guarantee statically (when used without debug assertions) that the type T is fully initialized and may be transmuted to its initialized form.

This pointer does not implement Deref or DerefMut, instead you should only use NeedsPinnedInit::begin_init on this type to begin safe initialization of the inner T.

Invariants and assumptions

• When the 'init lifetime expires, the value this pointer pointed to, will be initialized and have changed its type to T::Initialized.
• From the construction of a [NeedsPinnedInit<'init, T>] until the end of 'init it assumes full control over the pointee. This means that no one else is allowed to access the underlying value.

Implementations

impl<'init, T: PinnedInit> NeedsPinnedInit<'init, T>

pub unsafe fn new_unchecked(inner: Pin<&'init mut T>) -> Self

Construct a new NeedsPinnedInit from the given Pin.

Safety

• When the 'init lifetime expires, the value at inner will be initialized and have changed type to T::Initialized.
• From the moment this function is called until the end of 'init the produced NeedsPinnedInit becomes the only valid way to access the underlying value.
• The caller needs to guarantee, that the pointer from which inner was derived changes its pointee type to T::Initialized, when 'init ends.

pub fn begin_init(self) -> <T as BeginInit>::OngoingInit<'init>

Begin to initialize the value behind this NeedsPinnedInit.

pub unsafe fn as_ptr(&self) -> *const T

Get a raw const pointer to the value behind this NeedsPinnedInit.

Safety

The caller needs to carefully handle this pointer, because

• it is only valid for the duration that the underlying value T will live for (also counting the lifetime of the value when it is T::Initialized).
• it is pinned.
• you may only generate a *mut T or &mut T if the value of T is wrapped in an UnsafeCell.
• dereferencing the pointer outside of the initialization process of T, while 'init has not expired, is illegal (this would violate an invariant of NeedsPinnedInit).
• this pointer needs to be aware, that the type of the value pointed to will change from T to T::Initialized when 'init expires.

Storing this pointer inside of the T itself for example is sound.

pub unsafe fn as_ptr_mut(&mut self) -> *mut T

Get a raw mutable pointer to the value behind this NeedsPinnedInit.

Safety

The caller needs to carefully handle this pointer, because

• it is only valid for the duration that the underlying value T will live for (also counting the lifetime of the value when it is T::Initialized).
• it is pinned.
• you may only call this function if the value of T is wrapped in an UnsafeCell.
• dereferencing the pointer outside of the initialization process of T, while 'init has not expired, is illegal (this would violate an invariant of NeedsPinnedInit).
• this pointer needs to be aware, that the type of the value pointed to will change from T to T::Initialized when 'init expires.

Storing this pointer inside of the T itself for example is sound.

Trait Implementations

impl<'init, T: PinnedInit> Drop for NeedsPinnedInit<'init, T>

fn drop(&mut self)

Executes the destructor for this type.