Attribute Macro pin_project

Source

#[pin_project]

Expand description

An attribute that creates projection types covering all the fields of struct or enum.

This attribute creates projection types according to the following rules:

For the fields that use #[pin] attribute, create the pinned reference to the field.
For the other fields, create a normal reference to the field.

And the following methods are implemented on the original type:

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

By passing an argument with the same name as the method to the attribute, you can name the projection type returned from the method. This allows you to use pattern matching on the projected types.

#[pin_project(project = EnumProj)]
enum Enum<T> {
    Variant(#[pin] T),
}

impl<T> Enum<T> {
    fn method(self: Pin<&mut Self>) {
        let this: EnumProj<'_, T> = self.project();
        match this {
            EnumProj::Variant(x) => {
                let _: Pin<&mut T> = x;
            }
        }
    }
}

Note that the projection types returned by project and project_ref have an additional lifetime at the beginning of generics.

let this: EnumProj<'_, T> = self.project();
                   ^^

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

§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 attempt to provide an [Unpin] 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 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 an impl with #[pinned_drop]. This impl 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 way 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)] types. Attempting to use this attribute on a #[repr(packed)] type results in a compile-time error.

§Examples

#[pin_project] can be used on structs and enums.

use std::pin::Pin;

use pin_project::pin_project;

#[pin_project]
struct Struct<T, U> {
    #[pin]
    pinned: T,
    unpinned: U,
}

impl<T, U> Struct<T, U> {
    fn method(self: Pin<&mut Self>) {
        let this = self.project();
        let _: Pin<&mut T> = this.pinned;
        let _: &mut U = this.unpinned;
    }
}

use std::pin::Pin;

use pin_project::pin_project;

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

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

To use #[pin_project] on enums, you need to name the projection type returned from the method.

use std::pin::Pin;

use pin_project::pin_project;

#[pin_project(project = EnumProj)]
enum Enum<T, U> {
    Tuple(#[pin] T),
    Struct { field: U },
    Unit,
}

impl<T, U> Enum<T, U> {
    fn method(self: Pin<&mut Self>) {
        match self.project() {
            EnumProj::Tuple(x) => {
                let _: Pin<&mut T> = x;
            }
            EnumProj::Struct { field } => {
                let _: &mut U = field;
            }
            EnumProj::Unit => {}
        }
    }
}

When #[pin_project] is used on enums, only named projection types and methods are generated because there is no way to access variants of projected types without naming it. For example, in the above example, only the project method is generated, and the project_ref method is not generated. (When #[pin_project] is used on structs, both methods are always generated.)

impl<T, U> Enum<T, U> {
    fn call_project_ref(self: Pin<&Self>) {
        let _this = self.project_ref();
        //~^ ERROR no method named `project_ref` found for struct `Pin<&Enum<T, U>>` in the current scope
    }
}

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

use std::pin::Pin;

use pin_project::pin_project;

#[pin_project]
struct Struct<T> {
    #[pin]
    field: T,
}

impl<T> Struct<T> {
    fn call_project_twice(mut self: Pin<&mut Self>) {
        // `project` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`.
        self.as_mut().project();
        self.as_mut().project();
    }
}

§`!Unpin`

If you want to ensure that [Unpin] is not implemented, use the !Unpin argument to #[pin_project].

use pin_project::pin_project;

#[pin_project(!Unpin)]
struct Struct<T> {
    field: T,
}

This is equivalent to using #[pin] attribute for the PhantomPinned field.

use std::marker::PhantomPinned;

use pin_project::pin_project;

#[pin_project]
struct Struct<T> {
    field: T,
    #[pin] // <------ This `#[pin]` is required to make `Struct` to `!Unpin`.
    _pin: PhantomPinned,
}

Note that using PhantomPinned without #[pin] attribute has no effect.

§`UnsafeUnpin`

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

use pin_project::{pin_project, UnsafeUnpin};

#[pin_project(UnsafeUnpin)]
struct Struct<T, U> {
    #[pin]
    pinned: T,
    unpinned: U,
}

unsafe impl<T: Unpin, U> UnsafeUnpin for Struct<T, U> {}

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.

pub trait PinnedDrop {
    fn drop(self: Pin<&mut Self>);
}

#[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 std::{fmt::Debug, pin::Pin};

use pin_project::{pin_project, pinned_drop};

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

#[pinned_drop]
impl<T: Debug, U: Debug> PinnedDrop for PrintOnDrop<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 = PrintOnDrop { pinned_field: true, unpin_field: 40 };
}

§`project_replace` method

In addition to the project and project_ref methods which are always provided when you use the #[pin_project] attribute, there is a third method, project_replace which can be useful in some situations. It is equivalent to Pin::set, except that the unpinned fields are moved and returned, instead of being dropped in-place.

fn project_replace(self: Pin<&mut Self>, other: Self) -> ProjectionOwned;

The ProjectionOwned type is identical to the Self type, except that all pinned fields have been replaced by equivalent PhantomData types.

This method is opt-in, because it is only supported for [Sized] types, and because it is incompatible with the #[pinned_drop] attribute described above. It can be enabled by using #[pin_project(project_replace)].

For example:

use std::{marker::PhantomData, pin::Pin};

use pin_project::pin_project;

#[pin_project(project_replace)]
struct Struct<T, U> {
    #[pin]
    pinned_field: T,
    unpinned_field: U,
}

impl<T, U> Struct<T, U> {
    fn method(self: Pin<&mut Self>, other: Self) {
        let this = self.project_replace(other);
        let _: U = this.unpinned_field;
        let _: PhantomData<T> = this.pinned_field;
    }
}

By passing the value to the project_replace argument, you can name the returned type of the project_replace method. This is necessary whenever destructuring the return type of the project_replace method, and work in exactly the same way as the project and project_ref arguments.

use pin_project::pin_project;

#[pin_project(project_replace = EnumProjOwn)]
enum Enum<T, U> {
    A {
        #[pin]
        pinned_field: T,
        unpinned_field: U,
    },
    B,
}

let mut x = Box::pin(Enum::A { pinned_field: 42, unpinned_field: "hello" });

match x.as_mut().project_replace(Enum::B) {
    EnumProjOwn::A { unpinned_field, .. } => assert_eq!(unpinned_field, "hello"),
    EnumProjOwn::B => unreachable!(),
}

Attribute Macro pin_projectCopy item path

§Safety

§Examples

§!Unpin

§UnsafeUnpin

§#[pinned_drop]

§project_replace method

Attribute Macro pin_project

§`!Unpin`

§`UnsafeUnpin`

§`#[pinned_drop]`

§`project_replace` method