Trait PinInit

pub unsafe trait PinInit<T, E = Infallible>: Sized
where
    T: ?Sized,
{
    // Required method
    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E>;

    // Provided method
    fn pin_chain<F>(self, f: F) -> ChainPinInit<Self, F, T, E>
       where F: FnOnce(Pin<&mut T>) -> Result<(), E> { ... }
}

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> or even the stack (see stack_pin_init!).

Also see the module description.

Safety

When implementing this trait you will need to take great care. Also there are probably very few cases where a manual implementation is necessary. Use pin_init_from_closure where possible.

The PinInit::__pinned_init function:

• returns Ok(()) if it initialized every field of slot,
• returns Err(err) if it encountered an error and then cleaned slot, this means:
  • slot can be deallocated without UB occurring,
  • slot does not need to be dropped,
  • slot is not partially initialized.
• while constructing the T at slot it upholds the pinning invariants of T.

Required Methods

unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E>

Initializes slot.

Safety

• slot is a valid pointer to uninitialized memory.
• the caller does not touch slot when Err is returned, they are only permitted to deallocate.
• slot will not move until it is dropped, i.e. it will be pinned.

Provided Methods

fn pin_chain<F>(self, f: F) -> ChainPinInit<Self, F, T, E>

where F: FnOnce(Pin<&mut T>) -> Result<(), E>,

First initializes the value using self then calls the function f with the initialized value.

If f returns an error the value is dropped and the initializer will forward the error.

Examples

let mtx_init = CMutex::new(42);
// Make the initializer print the value.
let mtx_init = mtx_init.pin_chain(|mtx| {
    println!("{:?}", mtx.get_data_mut());
    Ok(())
});

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T, E> PinInit<T, E> for Result<T, E>

unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E>

Implementors

impl<T> PinInit<T> for T

impl<T, E, I, F> PinInit<T, E> for ChainInit<I, F, T, E>

where I: Init<T, E>, F: FnOnce(&mut T) -> Result<(), E>, T: ?Sized,

impl<T, E, I, F> PinInit<T, E> for ChainPinInit<I, F, T, E>

where I: PinInit<T, E>, F: FnOnce(Pin<&mut T>) -> Result<(), E>, T: ?Sized,