Trait pinned_init::PinInit

pub unsafe trait PinInit<T: ?Sized, E = Infallible>: 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!). Use the InPlaceInit::pin_init function of a smart pointer like Arc<T> on this.

Also see the module description.

Safety

When implementing this type 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

use pinned_init::pin_init_from_closure;
#[repr(C)]
struct RawFoo([u8; 16]);
extern {
    fn init_foo(_: *mut RawFoo);
}

#[pin_data]
struct Foo {
    #[pin]
    raw: RawFoo,
}

impl Foo {
    fn setup(self: Pin<&mut Self>) {
        println!("Setting up foo");
    }
}

let foo = pin_init!(Foo {
    raw <- unsafe { pin_init_from_closure(|slot| {
        init_foo(slot);
        Ok::<_, Infallible>(())
    }) },
}).pin_chain(|foo| {
    foo.setup();
    Ok(())
});

Object Safety

This trait is not object safe.

Implementors

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

impl<T: ?Sized, E, I, F> PinInit<T, E> for ChainInit<I, F, T, E>

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

impl<T: ?Sized, E, I, F> PinInit<T, E> for ChainPinInit<I, F, T, E>

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