[−][src]Trait pin_project::UnsafeUnpin
A trait used for custom implementations of [Unpin].
This trait is used in conjunction with the UnsafeUnpin
argument to #[pin_project]
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 Foo<K, V> { #[pin] field_1: K, field_2: V, } unsafe impl<K, V> UnsafeUnpin for Foo<K, V> where K: Unpin + Clone {}