[−][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 guarnatees 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. struturally
pinend fields) are also Unpin.
To help highlight this unsafety, the UnsafeUnpin trait is provided.
Implementing this trait is logically equivalent to implemnting 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 effectly 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 structually 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 {}