Rust Reference ยท Core Traits
The Unpin trait
Reference for Rust Unpin: the auto trait that allows a pinned value to move, Pin<P>, PhantomPinned, self-referential futures, and when you must care about it.
Unpin is an auto marker trait that says: "moving this value after it is pinned is harmless." Almost every type is Unpin: integers, String, Vec, your own structs made of such fields. For these types Pin<&mut T> is no different from a plain &mut T, and you can freely get the &mut T back.
Pinning matters for types that must not move once they have started, mainly the state machines the compiler builds for async blocks. Such a future may hold references to its own fields, and moving it would leave them dangling. Those futures are !Unpin, and Pin<P> is the wrapper that guarantees the pointee stays at its address.
use std::pin::Pin; let mut n = 5; let pinned: Pin<&mut i32> = Pin::new(&mut n); // allowed because i32: Unpin
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
pub auto trait Unpin {} pub struct PhantomPinned; // a zero-sized marker that is !Unpin Pin::new(&mut value) // requires T: Unpin Pin::into_inner(pin) // requires T: Unpin Box::pin(value) // Pin<Box<T>> for any T std::pin::pin!(value) // Pin<&mut T> on the stack, any T unsafe { pin.get_unchecked_mut() } // for !Unpin: you promise not to move it
| Part | Description |
|---|---|
T: Unpin |
Moving T after pinning is fine. Implemented automatically. |
!Unpin |
Opt out by including PhantomPinned (or any !Unpin field). |
Pin<P> |
A pointer wrapper (Pin<&mut T>, Pin<Box<T>>) that withholds &mut T for !Unpin targets. |
Errors / panics / edge cases: Pin::new on a !Unpin type fails to compile with "the trait bound PhantomPinned: Unpin is not satisfied". There is no runtime check; the unsafe pinning methods put the responsibility on you.
Usage notes
- It is about moves, not addresses.
Unpindoes not mean the value cannot be pinned; it means pinning adds no restrictions, soPin<&mut T>can be converted back to&mut Tsafely. - Futures from
async fnare!Unpin. To poll them manually or withselect-style combinators you pin them first, usingBox::pin(fut)orstd::pin::pin!(fut). Box<T>is alwaysUnpin(moving the box does not move its contents), butPin<Box<T>>still keeps the heap value in place.- Pointers do not infect.
&mut TandBox<T>areUnpinregardless ofT, so aPin<Box<dyn Future>>can itself be moved around. - Generic async code often writes
F: Future + Unpinto accept futures that can be polled through&mut Fwithout pinning them first. - When to use
PhantomPinned: only in types that hold self-references or are handed out to intrusive structures. Ordinary code never needs it. - Projection to fields of a pinned struct (
pin-projectstyle) is the hard part and isunsafeunless a macro does it for you.