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.

Implementors

impl<T, E> PinInit<T, E> 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,