Skip to content
Tutorials Center
My learning

Topics

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.

Rust
use std::pin::Pin;
let mut n = 5;
let pinned: Pin<&mut i32> = Pin::new(&mut n); // allowed because i32: Unpin

Try it

Rust Unpin types pin and unpin freely

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.

Rust Pinning a !Unpin value on the heap or the stack

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

Rust
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. Unpin does not mean the value cannot be pinned; it means pinning adds no restrictions, so Pin<&mut T> can be converted back to &mut T safely.
  • Futures from async fn are !Unpin. To poll them manually or with select-style combinators you pin them first, using Box::pin(fut) or std::pin::pin!(fut).
  • Box<T> is always Unpin (moving the box does not move its contents), but Pin<Box<T>> still keeps the heap value in place.
  • Pointers do not infect. &mut T and Box<T> are Unpin regardless of T, so a Pin<Box<dyn Future>> can itself be moved around.
  • Generic async code often writes F: Future + Unpin to accept futures that can be polled through &mut F without 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-project style) is the hard part and is unsafe unless a macro does it for you.