[−][src]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 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 aspin_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
, 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_fields(Unpin)]
, you do not need to ensure this because an appropriateUnpin
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 } } // You do not need to implement this manually. // 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::marker::Unpin; 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
.