Pin and Unpin

What it is and why it exists

Pin is a type-level contract around a pointer. Pin<P> does not freeze the variable P; it restricts moving the pointer’s target through that pointer. Moving a Pin<Box<T>> moves the handle that owns the allocation, but normally leaves the heap-resident T at the same address.

Most Rust values remain valid when moved from one place to another. A String’s stack-resident control data may change address while still owning the same buffer, and an ordinary struct should not store a raw pointer to one of its own fields. This default model keeps assignment, parameter passing, and container rearrangement straightforward.

Some values become address-sensitive during one phase of their lifetime. A self-referential structure stores its own address in a field, an intrusive data structure lets other nodes store its address, and some compiler-generated futures may retain internal borrows across suspension points. Once those relationships exist, a bytewise move would invalidate the stored addresses.

Unpin is an auto trait indicating that a type does not rely on pinning guarantees. i32, String, and most ordinary compositions implement it automatically; a type containing PhantomPinned does not. Unpin doesn’t mean “not currently moving.” It means moving the value remains sound even when it sits behind Pin.

Pin imposes a meaningful access restriction only when its target is !Unpin. For T: Unpin, Pin<&mut T>::get_mut() safely yields &mut T, after which callers can move the value with operations such as mem::replace. For T: !Unpin, the same conversion is unsafe, and its caller must prove that no address-sensitive part will move.

Pinning is not immutability. A Pin<&mut T> can call methods that mutate contents without moving pinned fields, and correctly designed projections can expose inner data. Conversely, a shared Pin<&T> prevents mutation because it contains a shared borrow, not because pinning itself means read-only.

Ordinary business structs, state machines containing only owned fields, and futures that do not depend on their own address rarely need hand-written pinning. You most often meet it when implementing Future::poll, designing an address-sensitive type, projecting pinned fields, or calling an async API that requires Pin<&mut T>.

How it works

The pinning contract starts at construction, not at the value’s birth. An address-sensitive type can move normally while it is still unpinned; only after Pin is established at its final location does code create relationships that depend on that address. A constructor must preserve that order: pin first, then write self-references.

Pin::new(pointer) is a safe constructor, but it requires the target to implement Unpin. It suits a value that was already safe to move and mainly provides a uniform interface. Box::pin(value) first puts the value in a Box allocation and then safely produces Pin<Box<T>>, even when T: !Unpin.

Pin::new_unchecked(pointer) can create a pinned pointer to a !Unpin target and is therefore unsafe. Its caller must guarantee more than stability at that line: until destruction finishes, no alias, owning-pointer operation, or drop path may move, deallocate, or repurpose the storage. The absence of a nearby move does not prove this long-term contract.

Safe access follows two paths based on Unpin. as_ref() and as_mut() create shorter pinned reborrows without surrendering the original relationship, while get_ref() obtains a shared reference. get_mut() exposes an ordinary mutable reference only when T: Unpin; get_unchecked_mut() transfers responsibility for not moving T to an unsafe caller.

Accessing a field from a pinned struct is called pin projection . Shared projection can ordinarily produce &Field; mutable projection must decide whether the field is structurally pinned or may be accessed as an ordinary &mut Field. That choice belongs to the type’s safety contract and cannot change ad hoc because a field happens to look like a String.

The flow below emphasizes state changes and responsibility. Once a value enters an address-sensitive state, safe APIs preserve its address; using unsafe to bypass those restrictions transfers the proof obligation to the caller.

The pinning invariant includes a drop guarantee: after a value enters its pinned state, its storage cannot become invalid or be repurposed before drop is called, and its address remains stable while destruction runs. Merely blocking explicit assignment is not enough; prematurely releasing the allocation would also break address-dependent destruction.

Pin::set shows that pinning does not mean a storage slot can never hold another value. It first completes destruction of the old value at its pinned address, then writes a new value into that location, so the old address-sensitive phase has ended correctly. It does not transfer old internal pointers into the new value.

PhantomPinned is a zero-sized !Unpin marker. Including it prevents a struct from automatically implementing Unpin, which stops safe code from obtaining an ordinary &mut Self through a mutable pin. It only closes that safe escape hatch; it does not initialize self-references, create a Pin, or validate projection code.

The Future trait uses self: Pin<&mut Self> so a concrete implementation may rely on staying put between polls. A simple future that implements Unpin can safely obtain &mut Self inside poll; an address-sensitive future must use pinned access instead. .await and executors arrange this condition before polling, so application code rarely calls poll directly.

Examples

All four programs below were compiled and run with the local rustc 1.94.0; they use only stable APIs that remain valid for the Rust 1.98 target. The output blocks contain the actual results.

Transparent access for an Unpin type

String implements Unpin, so a function receiving Pin<&mut String> can still call get_mut(). This example demonstrates interface compatibility, not a need to pin String.

Pin::new is available because String: Unpin. add_status mutates the string buffer’s contents, but this type never promised to depend on the address of the String control block. If a function only needs &mut String, accepting that reference directly is more honest; this signature exists solely to demonstrate how Unpin removes pinned-access restrictions.

Establishing a self-reference after pinning

Ticket points label_ptr at its own label field and opts out of Unpin with PhantomPinned. Its constructor calls Box::pin before writing the internal pointer in one small unsafe region.

use std::marker::PhantomPinned;
use std::pin::Pin;
use std::ptr;

struct Ticket {
    label: String,
    label_ptr: *const String,
    _pin: PhantomPinned,
}

impl Ticket {
    fn new(label: String) -> Pin<Box<Self>> {
        let mut ticket = Box::pin(Self {
            label,
            label_ptr: ptr::null(),
            _pin: PhantomPinned,
        });

        let label_ptr = &ticket.as_ref().get_ref().label as *const String;
        // SAFETY: the pointee is pinned before the pointer is stored.
        unsafe {
            ticket.as_mut().get_unchecked_mut().label_ptr = label_ptr;
        }
        ticket
    }

    fn label(self: Pin<&Self>) -> &str {
        // SAFETY: construction initializes a pointer into this pinned value.
        unsafe { &*self.get_ref().label_ptr }.as_str()
    }
}

fn main() {
    let ticket = Ticket::new(String::from("ticket-17"));
    let moved_handle = ticket;

    println!("{}", moved_handle.as_ref().label());
}

ticket-17

Assigning to moved_handle moves the Pin<Box<Ticket>> handle, not its heap pointee. Safe APIs cannot extract the Ticket, so label_ptr remains valid. This example uses a raw pointer and unsafe to expose the mechanism; application code should prefer indices, owned data, or an established projection tool rather than maintaining a self-reference by hand.

Polling through the Future contract

Countdown has no address-sensitive fields, so it implements Unpin automatically. The Future interface still requires a pinned receiver so the same trait can safely support state machines that do require pinning.

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll, Waker};

struct Countdown {
    remaining: u8,
}

impl Future for Countdown {
    type Output = &'static str;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        if self.remaining == 0 {
            Poll::Ready("complete")
        } else {
            self.remaining -= 1;
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

fn main() {
    let waker = Waker::noop();
    let mut context = Context::from_waker(waker);
    let mut countdown = Box::pin(Countdown { remaining: 1 });

    println!("{:?}", countdown.as_mut().poll(&mut context));
    println!("{:?}", countdown.as_mut().poll(&mut context));
}

Pending
Ready("complete")

The first poll decreases the count and notifies the waker; the second returns the result. Because Countdown: Unpin, field assignment works through Pin’s DerefMut implementation. Adding a structurally pinned field would require safe projection or a justified unsafe projection. A real executor schedules another poll from the wake notification instead of calling twice in immediate succession.

Replacing a pinned value with Pin::set

Phase is !Unpin because it contains PhantomPinned, yet Pin::set can still replace the whole value. The output order shows the old value completing destruction before the new value occupies the location.

use std::marker::PhantomPinned;

struct Phase {
    name: &'static str,
    _pin: PhantomPinned,
}

impl Drop for Phase {
    fn drop(&mut self) {
        println!("drop {}", self.name);
    }
}

fn main() {
    let mut phase = Box::pin(Phase {
        name: "queued",
        _pin: PhantomPinned,
    });

    phase.as_mut().set(Phase {
        name: "running",
        _pin: PhantomPinned,
    });
    println!("current {}", phase.name);
}

drop queued
current running
drop running

set guarantees that queued is destroyed first, rather than overwriting its bytes while an address-sensitive state still exists. The new Phase is then destroyed normally at the end of the scope. If the type must establish internal pointers, the replacement still needs to enter its own address-sensitive state through the type’s construction protocol; it cannot reuse old pointers.

Pitfalls

Treating a pinned pointer as an immovable handle

Fix: distinguish the pointer value from its pointee every time. When reviewing an assignment, state whether it moves a Pin<Box<T>> handle, the T itself, or one of T’s fields. Extracting, replacing, or copying the pointee’s bytes is the dangerous operation.

Assuming Pin restricts every type

Fix: first decide whether the type maintains a real address invariant. Use PhantomPinned or a genuinely !Unpin field when opting out of automatic Unpin; do not add Pin to solve an ordinary borrowing error.

Creating a self-reference before pinning

Fix: use two-phase initialization: place all ordinary fields in final storage and pin them, then write internal addresses through a controlled unsafe operation. The constructor should return a pinned handle such as Pin<Box<Self>>, not a freely movable Self.

Leaking a movable reference from unsafe projection

Fix: contain unsafe code in the smallest projection API, record which fields are pinned and which may move, and check that Drop follows the same choice. Prefer a mature macro or library when it can generate an already-reviewed projection implementation.

Implementing Unpin just to satisfy a bound

Fix: treat an Unpin bound as an API design signal and first use a pinned calling pattern or change the generic boundary. Implement Unpin only after proving that moves preserve every invariant, and protect types that must remain !Unpin with compile-fail tests.

Ignoring destruction and storage invalidation

Fix: review Deref, DerefMut, and Drop for any custom pointer used to create a Pin, and keep pinned fields in place until their destruction finishes. Use a safe API such as Pin::set when replacing the complete value so the required drop order is preserved.

Further reading

• Rust standard library: std::pin
• Rust standard library: Pin
• Rust standard library: Unpin
• Rust standard library: Future
• The Rust Programming Language: Futures and the async syntax