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

#[pin_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.

The following methods are implemented on the original #[pin_project] type:

fn project(self: Pin<&mut Self>) -> Projection<'_>;
fn project_ref(self: Pin<&Self>) -> ProjectionRef<'_>;

The visibility of the projected type and projection method is based on the original type. However, if the visibility of the original type is pub, the visibility of the projected type and the projection method is pub(crate).

If you want to call the project method multiple times or later use the original Pin type, it needs to use .as_mut() to avoid consuming the Pin.

Safety

This attribute is completely safe. In the absence of other unsafe code that you write, it is impossible to cause undefined behavior with this attribute.

This is accomplished by enforcing the four requirements for pin projection stated in the Rust documentation:

The struct must only be Unpin if all the structural fields are Unpin.

To enforce this, this attribute will automatically generate an Unpin implementation for you, which will require that all structurally pinned fields be Unpin If you wish to provide an manual Unpin impl, you can do so via the UnsafeUnpin argument.
The destructor of the struct must not move structural fields out of its argument.

To enforce this, this attribute will generate code like this:
```
struct MyStruct {}
trait MyStructMustNotImplDrop {}
impl<T: Drop> MyStructMustNotImplDrop for T {}
impl MyStructMustNotImplDrop for MyStruct {}
```
If you attempt to provide an Drop impl, the blanket impl will then apply to your type, causing a compile-time error due to the conflict with the second impl.

If you wish to provide a custom Drop impl, you can annotate a function with #[pinned_drop]. This function takes a pinned version of your struct - that is, Pin<&mut MyStruct> where MyStruct is the type of your struct.

You can call project() on this type as usual, along with any other methods you have defined. Because your code is never provided with a &mut MyStruct, it is impossible to move out of pin-projectable fields in safe code in your destructor.
You must make sure that you uphold the Drop guarantee: once your struct is pinned, the memory that contains the content is not overwritten or deallocated without calling the content's destructors.

Safe code doesn't need to worry about this - the only wait to violate this requirement is to manually deallocate memory (which is unsafe), or to overwrite a field with something else. Because your custom destructor takes Pin<&mut MyStruct, it's impossible to obtain a mutable reference to a pin-projected field in safe code.
You must not offer any other operations that could lead to data being moved out of the structural fields when your type is pinned.

As with requirement 3, it is impossible for safe code to violate this. This crate ensures that safe code can never obtain a mutable reference to #[pin] fields, which prevents you from ever moving out of them in safe code.

Pin projections are also incompatible with #[repr(packed)] structs. Attempting to use this attribute on a #[repr(packed)] struct results in a compile-time error.

Examples

Using #[pin_project] will automatically create the appropriate conditional Unpin implementation:

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

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

impl<T, U> Foo<T, U> {
    fn baz(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
    }
}

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

If you want to implement Unpin manually, you must use the UnsafeUnpin argument to #[pin_project].

use pin_project::{pin_project, UnsafeUnpin};
use std::pin::Pin;

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

impl<T, U> Foo<T, U> {
    fn baz(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
    }
}

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

Note the usage of the unsafe UnsafeUnpin trait, instead of the usual Unpin trait. UnsafeUnpin behaves exactly like Unpin, except that is unsafe to implement. This unsafety comes from the fact that pin projections are being used. If you implement UnsafeUnpin, you must ensure that it is only implemented when all pin-projected fields implement Unpin.

See UnsafeUnpin trait for more details.

`#[pinned_drop]`

In order to correctly implement pin projections, a type's Drop impl must not move out of any structurally pinned fields. Unfortunately, Drop::drop takes &mut Self, not Pin<&mut Self>.

To ensure that this requirement is upheld, the #[pin_project] attribute will provide a Drop impl for you. This Drop impl will delegate to an impl block annotated with #[pinned_drop] if you use the PinnedDrop argument to #[pin_project]. This impl block acts just like a normal Drop impl, except for the following two:

drop method takes Pin<&mut Self>
Name of the trait is PinnedDrop.

#[pin_project] implements the actual Drop trait via PinnedDrop you implemented. To drop a type that implements PinnedDrop, use the drop function just like dropping a type that directly implements Drop.

In particular, it will never be called more than once, just like Drop::drop.

For example:

use pin_project::{pin_project, pinned_drop};
use std::{fmt::Debug, pin::Pin};

#[pin_project(PinnedDrop)]
pub struct Foo<T: Debug, U: Debug> {
    #[pin]
    pinned_field: T,
    unpin_field: U,
}

#[pinned_drop]
impl<T: Debug, U: Debug> PinnedDrop for Foo<T, U> {
    fn drop(self: Pin<&mut Self>) {
        println!("Dropping pinned field: {:?}", self.pinned_field);
        println!("Dropping unpin field: {:?}", self.unpin_field);
    }
}

fn main() {
    let _x = Foo { pinned_field: true, unpin_field: 40 };
}

Supported Items

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

Structs (structs with named fields):

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

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

impl<T, U> Foo<T, U> {
    fn baz(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):

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

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

impl<T, U> Foo<T, U> {
    fn baz(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

pin_project also supports enums, but to use it, you need to use with the project attribute.

The attribute at the expression position is not stable, so you need to use a dummy #[project] attribute for the function.

use pin_project::{pin_project, project};
use std::pin::Pin;

#[pin_project]
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.

See also project and project_ref attributes.