Level 4 · Expert· Lesson 4 of 9 · 35 min
Pin and self-referential types
Why moving breaks self-references, what Pin guarantees, Unpin, structural pinning, and how async state machines depend on all of it.
The problem: moves are bitwise copies
Every Rust value can be moved, and a move is a memcpy to a new address followed by forgetting the old one. For almost all types that is harmless. It is fatal for a value that contains a pointer into itself:
struct SelfRef {
data: String,
ptr: *const String, // meant to point at `self.data`
}
fn main() {
let mut a = SelfRef { data: String::from("hello"), ptr: std::ptr::null() };
a.ptr = &a.data;
println!("before move: ptr == &data ? {}", std::ptr::eq(a.ptr, &a.data));
let b = a; // a bitwise move to a new stack slot
println!("after move: ptr == &data ? {}", std::ptr::eq(b.ptr, &b.data));
// b.ptr still holds the OLD address. Dereferencing it would be a use-after-move.
}
Safe Rust cannot even express such a type with references — there is no lifetime to write. But the compiler generates them constantly:
async fn example() {
let buf = [0u8; 64];
let view = &buf[..8]; // a reference to another local…
some_io().await; // …held across an await
println!("{}", view.len());
}
async fn some_io() {}
The future for example is a struct with fields buf and view, and view points into buf. Before the first poll it is inert and may be moved freely. After the first poll it must never move again.
Pin<P>
Pin<P> wraps a pointer type P (such as &mut T or Box<T>) and restricts its API so that the pointee cannot be moved through it.
The contract, for a pointee T that does not implement Unpin:
Once a value is pinned, its memory will not be moved, invalidated or repurposed until its destructor has run.
The mechanism is simply the absence of a safe way to get &mut T:
| Operation | Available when |
|---|---|
Pin::new(ptr) |
T: Unpin |
pin.get_mut() -> &mut T |
T: Unpin |
pin.as_ref() -> Pin<&T>, &*pin (shared access) |
always |
pin.as_mut() -> Pin<&mut T> (reborrow) |
always |
pin.set(value) (drops the old value in place, writes the new) |
always |
unsafe Pin::new_unchecked(ptr) |
you promise never to move the pointee |
unsafe pin.get_unchecked_mut() |
you promise not to move out of the result |
With a &mut T you could call mem::swap or mem::replace and move the value. Pin withholds exactly that.
Unpin
Unpin is an auto trait meaning “this type does not care about being moved, even when pinned”. Nearly every type is Unpin — integers, String, Vec, Box<T> for any T. For such types Pin<&mut T> and &mut T are freely interconvertible and pinning is a no-op.
The types that are not Unpin are compiler-generated futures and coroutines, and types that opt out by containing PhantomPinned.
A frequent confusion: Box<T> is always Unpin, even if T is not. Moving the box moves a pointer; the T on the heap stays put. That is exactly why Pin<Box<T>> works.
Pinning in practice
use std::future::Future;
use std::pin::{pin, Pin};
use std::task::{Context, Poll, Waker};
async fn compute() -> u32 {
40 + 2
}
fn main() {
let mut cx = Context::from_waker(Waker::noop());
// 1. Pin to the heap: the future can be stored, returned, put in collections.
let mut boxed: Pin<Box<dyn Future<Output = u32>>> = Box::pin(compute());
println!("{:?}", boxed.as_mut().poll(&mut cx));
// 2. Pin to the stack: no allocation; the future cannot escape this scope.
let mut local = pin!(compute());
println!("{:?}", local.as_mut().poll(&mut cx));
// `local` is a Pin<&mut impl Future>. The future itself lives in a hidden local that
// nothing else can name, so nothing can move it — which is what makes pin! sound.
let _: Poll<u32> = Poll::Pending; // (Poll is the return type of poll)
}
Future::poll takes self: Pin<&mut Self>. That signature is the reason for Pin: by the time anyone can poll, the future has been pinned, so the state machine may safely contain self-references.
A sound self-referential type
use std::marker::PhantomPinned;
use std::pin::Pin;
struct Parser {
input: String,
cursor: *const u8, // points into `input`'s heap buffer
owner: *const String, // points at the `input` FIELD itself: a true self-reference
_pin: PhantomPinned, // opt out of Unpin
}
impl Parser {
fn new(input: &str) -> Pin<Box<Parser>> {
let mut boxed = Box::pin(Parser {
input: input.to_string(),
cursor: std::ptr::null(),
owner: std::ptr::null(),
_pin: PhantomPinned,
});
// SAFETY: we only write fields; we never move the Parser out of the Box.
unsafe {
let this = boxed.as_mut().get_unchecked_mut();
this.cursor = this.input.as_ptr();
this.owner = &this.input;
}
boxed
}
fn input_via_self_pointer(self: Pin<&Self>) -> &str {
// SAFETY: `owner` points at our own `input` field, and we are pinned, so it is still there.
unsafe { &*self.owner }
}
fn advance(self: Pin<&mut Self>) -> Option<u8> {
// SAFETY: we mutate a field in place and do not move `self`.
let this = unsafe { self.get_unchecked_mut() };
let end = this.input.as_ptr().wrapping_add(this.input.len());
if this.cursor == end {
return None;
}
// SAFETY: cursor lies within input's buffer, which is never reallocated.
let byte = unsafe { *this.cursor };
this.cursor = this.cursor.wrapping_add(1);
Some(byte)
}
}
fn main() {
let mut p = Parser::new("pin");
while let Some(b) = p.as_mut().advance() {
print!("{} ", b as char);
}
println!("| {}", p.as_ref().input_via_self_pointer());
// let moved = *p; // ❌ would not compile: cannot move out of a Pin<Box<Parser>> (Parser: !Unpin)
}
Methods take self: Pin<&mut Self>, and the only way to construct a Parser yields one that is already pinned. Safe callers can never move it.
Structural pinning and projection
Given Pin<&mut Struct>, what may you do with a field? You must decide, per field, and stay consistent:
- Structurally pinned field: you project
Pin<&mut Struct>→Pin<&mut Field>. Then you must never move that field, must not offer&mut Field, and yourDropmust treat the field as pinned. - Not structurally pinned: you project to plain
&mut Field. Then the field’s type must not rely on pinning.
Hand-written projections are unsafe and easy to get wrong (a Drop impl receives &mut self, and #[repr(packed)] breaks the guarantee). Use the pin-project-lite or pin-project crates, which generate checked projections:
// crate: pin-project-lite
use pin_project_lite::pin_project;
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};
pin_project! {
/// Wraps a future and reports how long it took to complete.
struct Timed<F> {
#[pin]
inner: F, // structurally pinned: we poll it
started: Option<Instant>, // ordinary field
}
}
impl<F: Future> Future for Timed<F> {
type Output = (F::Output, Duration);
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
let this = self.project(); // inner: Pin<&mut F>, started: &mut Option<Instant>
let start = *this.started.get_or_insert_with(Instant::now);
match this.inner.poll(cx) {
Poll::Ready(v) => Poll::Ready((v, start.elapsed())),
Poll::Pending => Poll::Pending,
}
}
}
This is the shape of every hand-written future combinator.
The Drop guarantee
Pinning promises more than “no moves”: the memory must stay valid until drop runs. You may not deallocate or overwrite a pinned value’s storage without calling its destructor. Intrusive data structures depend on this — a node in an intrusive linked list unlinks itself in drop, and the list is sound only because the node cannot vanish without doing so. (Leaking the value is still allowed: then the memory simply stays valid forever.)
Exercises
- Take the first example and print both addresses before and after the move. Then wrap the value in
Box::pinand show that moving the box leaves the address unchanged. - Implement
Futureby hand forstruct Countdown(u32)that returnsPendingntimes (waking itself each time) and thenReady. Is itUnpin? Why does that make the implementation simpler? - Write
struct Join2<A: Future, B: Future>that polls two futures and completes with both outputs, usingpin-project-liteand twoOption<Output>slots. - Explain why
Pin<&mut T>beingDeref<Target = T>is harmless butDerefMutis implemented only forT: Unpin.
Check your understanding
Pick an answer to see the explanation.
1.What does
Pin<&mut T>guarantee whenT: !Unpin?2.Why is
Pin::get_mutavailable only whenT: Unpin?3.Why do futures produced by
asyncblocks generally not implementUnpin?