Skip to content

po4yka/rust-skills / skills/rust-pin-projection

rust-pin-projection

Verified

Use when adding Pin to a signature, writing a self-referential struct or other address-sensitive type, or projecting a pinned reference into a field (pin projection, structural pinning) by hand or via pin-project-lite. Also for choosing between std::pin::pin!, Box::pin, and Pin::new_unchecked; PhantomPinned and Unpin semantics; PinnedDrop; and errors such as "PhantomPinned cannot be unpinned", E0596 on a Pin, or an E0308 at a pin! call that says expected S, found &mut S (1.97 and 1.98 name unreachable_pin_macro_type_constraint). Not for polling, wakers, or cancel safety; use rust-async-internals.

Rust pin projection

Pin<&mut T> enforces nothing when T: Unpin, and !Unpin never makes a type unmovable. The restriction starts at the pin, and it applies only to a !Unpin type.

Diagnostics are from rustc 1.99.1 (edition 2024), pin-project 1.1.13, pin-project-lite 0.2.17, and Miri on nightly 2026-05-15.

Route the symptom to a section

Symptom or taskSection
You are about to write self: Pin<&mut Self>Pin enforces nothing
PhantomPinned, or a claim that a type "cannot move"Unpin does not mean movable
error[E0277]: PhantomPinned cannot be unpinnedGet a value pinned
error[E0515] or error[E0716] at a pin!Compile errors at a pin
error[E0308] at pin!(s): expected `S`, found `&mut S` (1.97 and 1.98 also name unreachable_pin_macro_type_constraint), or E0382 on a Pin<&mut T>Compile errors at a pin
Miri: allocN has been freed, so this pointer is danglingNever pin a named stack binding
error[E0133] from a macro_rules! that calls Pin::new_uncheckedNever pin a named stack binding
Miri: tag does not exist in the borrow stack, invalidated by a mem::swap; or you wrote impl<T> Unpin for MyType<T> {}Obligation 1 in Structural pinning
impl Drop or #[repr(packed)] on a type with a pinned fieldObligation 2
A pinned value sits in ManuallyDrop, or its storage is overwritten or freed before its destructor runsObligation 3
error[E0596]: cannot borrow data in dereference of Pin<&mut T> as mutableObligation 4
You choose between pin-project and pin-project-liteThe projection macros
You write a smart pointer that a caller may wrap in PinYour own pinning pointer type
You must overwrite a pinned valueUse Pin::set: it is safe and drops the old value in place. Read references/pin-projection-macros.md (section "Assign into a pinned value") for the example
You must prove a pinned type sound, or stay !UnpinVerify
You review code that pins or projectsRead references/pin-projection-macros.md (section "Review checklist")

Verify

ClaimCheckWhat a pass does not prove
No pinned value moves, is overwritten, or loses its destructorWhen a nightly toolchain with the miri component is installed, run cargo +nightly miri test --locked on the crate that holds Pin::new_unchecked, map_unchecked_mut, get_unchecked_mut, a manual Unpin, or a manual Drop on a pinned type. Run it before you merge such a change, and in CI for that crate. Without Miri, report the pinning code as not checked by MiriPaths the tests do not run. A pinning defect stays silent until code uses a stored pointer to the pinned value, so a test must pin the value, store the pointer, do the operation under test (move, swap, drop, overwrite), and then use the pointer
An address-sensitive type stays !UnpinA compile_fail doctest, or a trybuild case, that calls assert_unpin::<T>(). Read references/pin-projection-macros.md (section "Prove the Unpin result with a test") when you write the testA compile_fail doctest passes on any compile error, a typo included. trybuild compares the full error text
A type you promise is Unpin stays UnpinA normal test that calls assert_unpin::<T>()Anything about soundness
It buildscargo build, cargo test, cargo clippyPin soundness

A change that pins or projects is complete when the Miri row passes (or the report says that Miri did not run), the Unpin tests hold, and the review checklist holds. The rust-sanitizers-miri skill, when it is installed, owns the Miri flags and the aliasing-model policy; the Tree Borrows lane is MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test --locked.

Pin enforces nothing for an Unpin target

Check this before you add Pin to any signature. Pin::new and Pin::get_mut are both safe for an Unpin target, and Pin<Ptr> implements DerefMut for one, so safe code moves the value out through any of them.

  • Write Pin in a signature only when the type is !Unpin, or when a trait such as Future forces the receiver. Otherwise take &mut self.
  • Add a PhantomPinned field to the type whose address must stay stable. That one field removes the auto Unpin impl and turns the API from documentation into enforcement.

Unpin does not mean movable

Every Rust type moves, !Unpin included: assignment, mem::swap through &mut, Box::new, and vec![..] all move a PhantomPinned type with no unsafe and no warning. Only trait bounds read Unpin: Pin::new, Pin::get_mut, DerefMut for Pin<Ptr>, and impls such as Future for &mut F. Read T: !Unpin as "once a value is pinned, safe code cannot reach &mut T again". Read references/pin-projection-macros.md (section "Moves that Pin does not stop") when a design depends on a type that "cannot move".

Get a value pinned

ConstructorResultUnsafeEscapes the frameAllocates
std::pin::pin!(value)Pin<&mut T>nonono
Box::pin(value)Pin<Box<T>>noyesyes
Pin::new(&mut value)Pin<&mut T>no, needs T: Unpinnono
unsafe { Pin::new_unchecked(&mut value) }Pin<&mut T>yesnono

std::pin::pin! is stable since 1.68 and needs no crate. Pin::new on a !Unpin type fails with error[E0277]: `PhantomPinned` cannot be unpinned and the advice to use pin! or Box::pin. Take that advice. Do not reach for Pin::new_unchecked. The examples use SelfRef, a struct whose ptr field points into its own buf field; read references/pin-projection-macros.md (section "The SelfRef example") for its definition.

Never pin a named stack binding

Pin::new_unchecked(&mut local) commits the value for the rest of its life, but the Pin drops first, and safe code then moves the local. Cargo, rustc, and Clippy stay silent; Miri reports allocN has been freed, so this pointer is dangling.

  • Never call Pin::new_unchecked on a binding you can still name. Use std::pin::pin!, which puts the value in an unnameable temporary, or Box::pin, which owns it. Drop::drop is the one exception: there the value is never used again after the call.
  • Call Pin::new_unchecked only on a pointer you own for the whole life of the value.
  • Never hand-roll a stack pinning macro_rules!. Wrapping its call in unsafe { .. } to fix E0133 scopes the shadow to that block, and the original binding moves out. Delete the macro and use std::pin::pin!.

Read references/structural-pinning.md (section "A named stack binding") when you must explain either failure in a review.

Structural pinning: the four obligations

A projection Pin<&mut Self> -> Pin<&mut Field>, written with Pin::map_unchecked_mut, makes the field structurally pinned. A field that is not structurally pinned projects to a plain &mut through Pin::get_unchecked_mut. Choose per field, and state the choice in the SAFETY: comment. Break one of these obligations, and safe callers get undefined behaviour:

  1. Structural Unpin. Never write impl Unpin by hand on a type that has a pinning projection. It needs no unsafe, so it passes an unsafe-focused review, and it makes Pin::get_mut safe. Delete the impl, and let the auto trait decide.
  2. Pinned destruction. Drop::drop gets &mut self for a pinned value. Write the destructor as if the receiver were Pin<&mut Self>: use PinnedDrop under a macro, or an inner function that takes the pin. Reject #[repr(packed)] on a pinned type yourself: drop glue can move a packed field, and rustc does not warn.
  3. Notice of destruction. Never free, overwrite, or reuse the storage of a pinned !Unpin value before its destructor runs: no ManuallyDrop around it, no ptr::write over it, no Vec::set_len below it. Call ptr::drop_in_place first. Pin::set is sound. A destructor that can panic part way must abort instead; by default, make each Drop infallible.
  4. No move-out operation. Expose no take, replace, or swap on a structurally pinned field. The type system rejects them (E0596) once the projection returns Pin<&mut Field>.

Read references/structural-pinning.md when you write or review a projection, a destructor, or storage of pinned values.

The projection macros

Write the projection with a macro. A hand-written map_unchecked_mut is correct only while all four obligations hold, and no build step checks that. Take pin-project-lite when the dependency graph builds no proc-macro crate yet. Take pin-project for a tuple struct or tuple variant, for UnsafeUnpin, or for its rejection of every #[repr(packed)] struct. Read references/pin-projection-macros.md (section "Choose the crate") when you choose.

Both macros replace the auto Unpin impl with one that reads the #[pin] fields alone. A PhantomPinned field without #[pin] therefore leaves the struct Unpin, with no diagnostic. Add #[pin] to the PhantomPinned field, or put #[project(!Unpin)] (pin-project-lite) or #[pin_project(!Unpin)] (pin-project) on the type. Hold that result with a compile-fail test.

Your own pinning pointer type

Pin<P> pins P::Target only when P is a real indirection: a struct Inline<T>(T) whose Deref returns &self.0 moves the "pinned" data with every move of the Pin<P>. Read references/pin-projection-macros.md (section "A pinning pointer that pins nothing") for the three rules such a type must keep.

Compile errors at a pin

ErrorFix
E0716 or E0515 at a pin! passed as an argument or returnedThe temporary dies at the end of the statement. Bind first (let mut p = pin!(v);), then pass p.as_mut(). Use Box::pin when the value must outlive the function
E0308 expected `S`, found `&mut S` at pin!(s) with s: &mut SSince 1.97, pin!(r) gives Pin<&mut &mut T>. Take Pin<&mut S>, use Pin::new(s) for an Unpin target, or take s: S by value. Never unsafe { Pin::new_unchecked(s) } and never pin!(&mut s): the caller can still move the value
E0382: use of moved value: `p` on a Pin<&mut T>Pin<&mut T> is not Copy and is not reborrowed implicitly. Call .as_mut() before every call except the last, and declare let mut p

Read references/pin-projection-macros.md (sections "How long a pin! value lives" and "pin! of a &mut reference") when the error names a pin! nested in a tuple, a struct literal, or Some(..).

Related skills

When installed: rust-async-internals owns polling, select!, and cancel safety; rust-unsafe owns the SAFETY: comment convention and the #[repr(packed)] rules behind E0793; rust-macros owns macro_rules! hygiene.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall