Types which can be safely moved after being pinned.
Since Rust itself has no notion of immovable types, and considers moves
(e.g. through assignment or
mem::replace) to always be safe,
this trait cannot prevent types from moving by itself.
Instead it is used to prevent moves through the type system,
by controlling the behavior of pointers
P wrapped in the
which "pin" the type in place by not allowing it to be moved out of them.
pin module documentation for more information on pinning.
Implementing this trait lifts the restrictions of pinning off a type,
which then allows it to move out with functions such as
Unpin has no consequence at all for non-pinned data. In particular,
mem::replace happily moves
!Unpin data (it works for any
&mut T, not
T: Unpin). However, you cannot use
mem::replace on data wrapped inside a
Pin<P> because you cannot get the
&mut T you need for that, and that is what makes this system work.
So this, for example, can only be done on types implementing
use std::mem; use std::pin::Pin; let mut string = "this".to_string(); let mut pinned_string = Pin::new(&mut string); // We need a mutable reference to call `mem::replace`. // We can obtain such a reference by (implicitly) invoking `Pin::deref_mut`, // but that is only possible because `String` implements `Unpin`. mem::replace(&mut *pinned_string, "other".to_string());Run
This trait is automatically implemented for almost every type.