Trait pin_project::UnsafeUnpin [−][src]
A trait used for custom implementations of Unpin.
This trait is used in conjunction with the UnsafeUnpin argument to
the #[pin_project] attribute.
The Rust Unpin trait is safe to implement - by itself,
implementing it cannot lead to undefined behavior.
Undefined behavior can only occur when other unsafe code is used.
It turns out that using pin projections, which requires unsafe code,
imposes additional requirements on an Unpin impl. Normally, all of this
unsafety is contained within this crate, ensuring that it’s impossible for
you to violate any of the guarantees required by pin projection.
However, things change if you want to provide a custom Unpin impl
for your #[pin_project] type. As stated in the Rust
documentation, you must be sure to only implement Unpin
when all of your #[pin] fields (i.e. structurally pinned fields) are also
Unpin.
To help highlight this unsafety, the UnsafeUnpin trait is provided.
Implementing this trait is logically equivalent to implementing Unpin -
this crate will generate an Unpin impl for your type that ‘forwards’ to
your UnsafeUnpin impl. However, this trait is unsafe - since your type
uses structural pinning (otherwise, you wouldn’t be using this crate!),
you must be sure that your UnsafeUnpin impls follows all of
the requirements for an Unpin impl of a structurally-pinned type.
Note that if you specify #[pin_project(UnsafeUnpin)], but do not
provide an impl of UnsafeUnpin, your type will never implement Unpin.
This is effectively the same thing as adding a PhantomPinned to your
type.
Since this trait is unsafe, impls of it will be detected by the
unsafe_code lint, and by tools like cargo geiger.
Examples
An UnsafeUnpin impl which, in addition to requiring that structurally
pinned fields be Unpin, imposes an additional requirement:
use pin_project::{pin_project, UnsafeUnpin}; #[pin_project(UnsafeUnpin)] struct Struct<K, V> { #[pin] field_1: K, field_2: V, } unsafe impl<K, V> UnsafeUnpin for Struct<K, V> where K: Unpin + Clone {}