Struct pin_init::PinInit

pub struct PinInit<'a, T> { /* fields omitted */ }

A pinned, uninitialized pointer.

This can be considered as Pin<&mut MaybeUninit<T>>:

• The pointee has a stable location in memory. It cannot be moved elsewhere.
• The pointee is not yet initialized, therefore the drop guarantee is not existent.

However, PinInit provides the additional guarantee that once a method that successfully initialze the data is called (e.g. init_ok), the pointee will be considered as Pin<&mut T>, therefore the drop guarantee kicks in, and T’s destructor is guaranteed to be called before the storage is deallocated.

Implementations

impl<'a, T> PinInit<'a, T>

pub unsafe fn new(ptr: &'a mut MaybeUninit<T>) -> Self

Creates a new PinInit with a given MaybeUninit<T>.

Safety

The caller must ensure ptr has a stable location in memory.

The caller must obtain a PinInitResult that is tied to the lifetime of the returned PinInit, and need to respect its value:

• If PinInitOk is obtained, the caller must treat the ptr as Pin<&mut T>. This means that the drop guarantee kick in; the memory cannot be deallocated until T is dropped.
• If PinInitErr is obtained, ptr is uninitialized and the caller must not try to drop T.
• If panic happens while trying to get the result, then we are not certain about initialization state. This means that the caller must respect the drop guarantee, but also not drop the value. The only solution is to leak memory. If that’s not possible, then the caller must abort the process.

The lifetime associated with this function should be “closed”. It should be a local, temporary lifetime, shorter than any of the lifetime the caller have access to (including 'static, and should not escape the calling function. This is to guarantee that the only way to get a PinInitResult<'a, T, E> is to use of the methods of this particular PinInit returned. In order to satisfy the requirement, the caller typically takes a constructor with type for<'a> FnOnce(PinInit<'a, T>) -> PinInitResult<'a, T, E>.

pub fn get_mut(&mut self) -> &mut MaybeUninit<T>

Gets a mutable reference to MaybeUninit inside of this PinInit.

This is safe because the MaybeUninit we point to is not yet initialized, and MaybeUninit does not have Drop implementation.

pub unsafe fn init_ok(self) -> PinInitOk<'a, T>

Asserts that the initialize is indeed completed. Doing so initiates the drop guarantee of T.

Safety

This function is unsafe as this is equivalent to MaybeUninit::assume_init.

pub fn init_err<E>(self, err: E) -> PinInitErr<'a, E>

Generates a PinInitResult signaling that the initialization is failed.

Note that the caller should make sure nothing is partially pinned-initialized. This isn’t the contract of this function, but is the contract for creating PinInit for pinned-initializing sub-fields.

pub fn init<E, F>(self, value: F) -> PinInitResult<'a, T, E> where
    F: FnOnce(Self) -> PinInitResult<'a, T, E>, 

Completes the initialization with a callback.

Useful e.g. if the callback is produced by init_pin!.

pub fn init_with_value(self, value: T) -> PinInitOk<'a, T>

Completes the initialization by moving the given value.

Useful if the the type T can be initialized unpinned.