[−][src]Attribute Macro pin_project::unsafe_project

#[unsafe_project]

An attribute that creates a projection struct covering all the fields.

This attribute creates a projection struct according to the following rules:

For the field that uses #[pin] attribute, makes the pinned reference to the field.
For the other fields, makes the unpinned reference to the field.

Safety

For the field that uses #[pin] attribute, three things need to be ensured:

If the struct implements Drop, the drop method is not allowed to move the value of the field.
If the struct wants to implement Unpin, it has to do so conditionally: The struct can only implement Unpin if the field's type is Unpin. If you use #[unsafe_project(Unpin)], you do not need to ensure this because an appropriate conditional Unpin implementation will be generated.
The struct must not be #[repr(packed)].

For the other fields, need to be ensured that the contained value not pinned in the current context.

Examples

Using #[unsafe_project(Unpin)] will automatically create the appropriate conditional Unpin implementation:

use pin_project::unsafe_project;
use std::pin::Pin;

#[unsafe_project(Unpin)]
struct Foo<T, U> {
    #[pin]
    future: T,
    field: U,
}

impl<T, U> Foo<T, U> {
    fn baz(mut self: Pin<&mut Self>) {
        let this = self.project();
        let _: Pin<&mut T> = this.future; // Pinned reference to the field
        let _: &mut U = this.field; // Normal reference to the field
    }
}

// Automatically create the appropriate conditional Unpin implementation.
// impl<T, U> Unpin for Foo<T, U> where T: Unpin {}

If you want to implement Unpin manually:

use pin_project::unsafe_project;
use std::pin::Pin;

#[unsafe_project]
struct Foo<T, U> {
    #[pin]
    future: T,
    field: U,
}

impl<T, U> Foo<T, U> {
    fn baz(mut self: Pin<&mut Self>) {
        let this = self.project();
        let _: Pin<&mut T> = this.future; // Pinned reference to the field
        let _: &mut U = this.field; // Normal reference to the field
    }
}

impl<T: Unpin, U> Unpin for Foo<T, U> {} // Conditional Unpin impl

Note that borrowing the field where #[pin] attribute is used multiple times requires using .as_mut() to avoid consuming the Pin.

Supported Items

The current version of pin-project supports the following types of items.

Structs (structs with named fields):

#[unsafe_project(Unpin)]
struct Foo<T, U> {
    #[pin]
    future: T,
    field: U,
}

impl<T, U> Foo<T, U> {
    fn baz(mut self: Pin<&mut Self>) {
        let this = self.project();
        let _: Pin<&mut T> = this.future;
        let _: &mut U = this.field;
    }
}

Tuple structs (structs with unnamed fields):

#[unsafe_project(Unpin)]
struct Foo<T, U>(#[pin] T, U);

impl<T, U> Foo<T, U> {
    fn baz(mut self: Pin<&mut Self>) {
        let this = self.project();
        let _: Pin<&mut T> = this.0;
        let _: &mut U = this.1;
    }
}

Structs without fields (unit-like struct and zero fields struct) are not supported.

Enums

unsafe_project also supports enums, but to use it ergonomically, you need to use the project attribute.

use pin_project::{project, unsafe_project};

#[unsafe_project(Unpin)]
enum Foo<A, B, C> {
    Tuple(#[pin] A, B),
    Struct { field: C },
    Unit,
}

impl<A, B, C> Foo<A, B, C> {
    #[project] // Nightly does not need a dummy attribute to the function.
    fn baz(self: Pin<&mut Self>) {
        #[project]
        match self.project() {
            Foo::Tuple(x, y) => {
                let _: Pin<&mut A> = x;
                let _: &mut B = y;
            }
            Foo::Struct { field } => {
                let _: &mut C = field;
            }
            Foo::Unit => {}
        }
    }
}

Enums without variants (zero-variant enums) are not supported.

Also see project attribute.