FerrousPath

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 your Drop must 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

  1. Take the first example and print both addresses before and after the move. Then wrap the value in Box::pin and show that moving the box leaves the address unchanged.
  2. Implement Future by hand for struct Countdown(u32) that returns Pending n times (waking itself each time) and then Ready. Is it Unpin? Why does that make the implementation simpler?
  3. Write struct Join2<A: Future, B: Future> that polls two futures and completes with both outputs, using pin-project-lite and two Option<Output> slots.
  4. Explain why Pin<&mut T> being Deref<Target = T> is harmless but DerefMut is implemented only for T: Unpin.

Check your understanding

Pick an answer to see the explanation.

  1. 1.What does Pin<&mut T> guarantee when T: !Unpin?

  2. 2.Why is Pin::get_mut available only when T: Unpin?

  3. 3.Why do futures produced by async blocks generally not implement Unpin?

Key terms in this lesson

Finished the lesson and the exercises?