---

name: rust-pin description: "Pin 与自引用类型专家。处理 Pin, Unpin, self-referential, Future, async, Generator, Pinning projection 等问题。触发词：Pin, Unpin, self-referential, Future, async, Generator, 自引用, Pinning" globs: ["**/*.rs"]

Pin 与自引用

核心问题

如何在异步或自引用结构中保证指针稳定性？

Pin 确保某些类型在内存中不会移动。

---

什么时候需要 Pin

1. async/await 的 Future

Copyuse std::pin::Pin;
use std::task::{Context, Poll};

struct MyFuture {
    state: State,
}

impl Future for MyFuture {
    type Output = ();
    
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.get_mut();
        // 安全使用 this.state
        Poll::Ready(())
    }
}

2. 自引用结构

Copyuse std::pin::Pin;

struct Node {
    value: i32,
    parent: Option<Pin<Box<Node>>>,  // 自引用
}

---

Pin 的四种使用方式

---

Unpin marker

Copy// 类型可以实现 Unpin 表示它不介意被移动
struct MyType {
    data: Vec<u8>,
}

// Unpin 自动实现，大多数类型不需要手动实现
// 哪些类型没有实现 Unpin？
// - Future (async/await 生成的)
// - Generator
// - 手动用 !Unpin 标记的类型

struct NotUnpinType {
    // 包含自引用指针
    ptr: *const Self,
}

impl !Unpin for NotUnpinType {}

---

Pinning Projection

Copystruct Wrapper<T> {
    inner: T,
    extra: String,
}

impl<T> Pin for Wrapper<T> where T: Unpin {
    // projection 到 inner
    fn project(self: Pin<&mut Self>) -> Pin<&mut T> {
        // SAFETY: Wrapper is pinned, inner is inside it
        unsafe {
            &mut self.get_unchecked_mut().inner
        }
    }
}

---

常见错误

---

什么时候不需要 Pin

• 同步代码，不涉及 future
• 数据结构不包含自引用
• 栈上的临时值
• 明确知道值不会被移动

---

使用场景速查