[−][src]Attribute Macro pin_project::unsafe_project
#[unsafe_project]
An attribute that would create 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
, thedrop
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 implementUnpin
if the field's type isUnpin
. If you use#[unsafe_project(Unpin)]
, you do not need to ensure this because an appropriate conditionalUnpin
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 {} // Conditional Unpin impl
If you want to implement Unpin
manually:
use pin_project::unsafe_project; use std::marker::Unpin; 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 two 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; // Pinned reference to the field let _: &mut U = this.field; // Normal reference to the 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; // Pinned reference to the field let _: &mut U = this.1; // Normal reference to the field } }
Structs without fields (unit-like struct and zero fields struct) are not supported.