PinUninit

Struct PinUninit 

Source
pub struct PinUninit<'a, T> { /* private fields */ }
Expand description

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

Source§

impl<'a, T> PinUninit<'a, T>

Source

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

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

§Safety

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

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

  • If InitOk 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 InitErr 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 InitResult<'a, T, E> is to use of the methods of this particular PinUninit returned. In order to satisfy the requirement, the caller typically takes a constructor with type Init<T, E>, which can be seen as for<'a> FnOnce(PinUninit<'a, T>) -> InitResult<'a, T, E>.

Source

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

Gets a mutable reference to MaybeUninit inside of this PinUninit.

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

Source

pub unsafe fn init_ok(self) -> InitOk<'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.

Source

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

Generates a InitResult 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 PinUninit for pinned-initializing sub-fields.

Source

pub fn init<E, F>(self, value: F) -> InitResult<'a, T, E>
where F: Init<T, E>,

Completes the initialization with a callback.

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

Source

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

Completes the initialization by moving the given value.

Useful if the the type T can be initialized unpinned.

Auto Trait Implementations§

§

impl<'a, T> Freeze for PinUninit<'a, T>

§

impl<'a, T> RefUnwindSafe for PinUninit<'a, T>
where T: RefUnwindSafe,

§

impl<'a, T> !Send for PinUninit<'a, T>

§

impl<'a, T> !Sync for PinUninit<'a, T>

§

impl<'a, T> Unpin for PinUninit<'a, T>

§

impl<'a, T> !UnwindSafe for PinUninit<'a, T>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, E> Init<T, E> for T

Source§

fn __init<'a>( self, this: PinUninit<'a, T>, ) -> Result<InitOk<'a, T>, InitErr<'a, E>>

Pin-initialize this.
Source§

fn map_err<E2, F>(self, f: F) -> MapErr<T, E, E2, Self, F>
where F: FnOnce(E) -> E2,

Maps the error from E to E2.
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.