[−][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
, 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 {}
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.