Attribute Macro pin_project::unsafe_fields

#[unsafe_fields]

An attribute that would create projections for each struct fields.

This is similar to unsafe_project, but it is compatible with pin-utils.

This attribute is available if pin-project is built with the "unsafe_fields" feature.

This attribute creates methods according to the following rules:

• For the field that uses #[pin] attribute, the method that makes the pinned reference to that field is created. This is the same as pin_utils::unsafe_pinned.
• For the field that uses #[skip] attribute, the method referencing that field is not created.
• For the other fields, the method that makes the unpinned reference to that field is created. This is the same as pin_utils::unsafe_unpinned.

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_fields(Unpin)], you do not need to ensure this because an appropriate 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_fields(Unpin)] will automatically create the appropriate Unpin implementation:

use pin_project::unsafe_fields;
use std::pin::Pin;

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

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

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

If you want to implement Unpin manually:

use pin_project::unsafe_fields;
use std::pin::Pin;

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

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

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

Note that borrowing the field multiple times requires using .as_mut() to avoid consuming the Pin.