Pin 与 Unpin

是什么，为什么存在

Pin 是围绕指针的类型级契约。Pin<P> 不会冻结变量 P，而是限制你通过这个指针移动它的目标值。移动 Pin<Box<T>> 只会移动拥有堆分配的指针句柄，通常不会改变堆上 T 的地址。

大多数 Rust 值从一个位置移动到另一个位置时仍然有效。String 的栈上控制信息可以换地址，只要它仍然拥有同一块缓冲区；普通结构体的字段也不应保存指向自身其他字段的裸指针。这个默认模型让赋值、传参和容器重排保持简单。

有些值在生命周期的某一阶段会变成地址敏感值（address-sensitive value）。自引用结构在字段中保存自身地址，侵入式数据结构让其他节点保存其地址，编译器生成的某些 future 则可能在状态中保存跨挂起点的内部借用。它们一旦建立这种关系，再做按位移动就会使内部地址失效。

Unpin 是自动 trait，表示类型不依赖固定保证。i32、String 和绝大多数普通组合类型会自动实现它；包含 PhantomPinned 的类型默认不会实现。Unpin 不是「当前没有移动」，而是「即使放在 Pin 后面，移动该值也不会破坏地址不变量」。

Pin 只有在目标为 !Unpin 时才施加实际访问限制。对于 T: Unpin，Pin<&mut T>::get_mut() 可以安全地产生 &mut T，调用方随后可以用 mem::replace 等操作移动值。对于 T: !Unpin，同样的转换需要 unsafe，调用者必须自行证明它不会移动地址敏感部分。

固定也不等于不可变。Pin<&mut T> 可以调用只修改内容但不移动固定字段的方法，还可以通过正确的字段投影操作内部数据。反过来，一个共享的 Pin<&T> 不允许修改，原因来自共享借用，不是来自固定本身。

普通业务结构、只保存拥有型字段的状态机，以及不会依赖自身地址的 future 通常不需要手写 Pin。你最常在实现 Future::poll、设计地址敏感类型、编写固定字段投影，或调用要求 Pin<&mut T> 的异步 API 时遇到它。

工作原理

固定契约从构造开始，而不是从值出生时开始。地址敏感类型可以先作为普通未固定值移动；在最终位置建立 Pin 后，代码才创建依赖该地址的内部关系。构造器必须保证两件事的顺序：先固定，后写入自引用。

Pin::new(pointer) 是安全构造器，但要求目标实现 Unpin。它适合本来就能安全移动的值，因此主要提供统一接口。Box::pin(value) 会先把值放入 Box 的分配，再安全地产生 Pin<Box<T>>，即使 T: !Unpin 也可使用。

Pin::new_unchecked(pointer) 可以为 !Unpin 目标创建固定指针，因此是 unsafe。调用者不仅要保证当前地址稳定，还要保证从此直到目标析构完成，任何别名、拥有指针实现和析构路径都不会移动、释放或复用该存储。局部看起来没有移动并不足以证明这个长期契约。

安全访问根据 Unpin 分成两条路径。as_ref() 与 as_mut() 创建更短的固定重借用，不放弃原固定关系；get_ref() 取得共享引用。get_mut() 只在 T: Unpin 时提供普通可变引用，而 get_unchecked_mut() 把不移动 T 的责任交给 unsafe 调用方。

从固定结构体访问字段称为 固定投影（pin projection） 。普通共享投影通常直接产生 &Field；可变投影必须先决定字段是结构性固定字段，还是允许作为普通 &mut Field 访问的非固定字段。这个决定属于类型的安全契约，不能根据「字段看起来是 String」临时改变。

下面的流程强调状态变化和责任转移。进入地址敏感状态之后，安全 API 保持相同地址；如果使用 unsafe 绕过限制，证明责任就落到调用者身上。

固定不变量（pinning invariant） 包含析构保证：进入固定状态的值在 drop 被调用之前，存储不能失效或被重新用于别的值，而且析构执行期间地址仍然稳定。只禁止显式赋值还不够；提前释放分配会让依赖该地址的析构逻辑同样失效。

Pin::set 说明固定并不意味着存储槽永远不能换值。该方法先在原地址完成旧值的析构，再把新值写入相同位置，所以旧值的地址敏感阶段已经正确结束。它不会把旧的内部指针自动转移给新值。

PhantomPinned 是一个零大小的 !Unpin 标记。把它放进结构体会阻止结构体自动实现 Unpin，从而使安全代码不能从固定可变引用取得普通 &mut Self。它只关闭这条安全出口，不会初始化自引用、创建 Pin 或验证投影代码。

Future trait 把接收者写成 self: Pin<&mut Self>，这样具体 future 实现可以依赖轮询之间不被移动。实现了 Unpin 的简单 future 可以在 poll 中安全取得 &mut Self；地址敏感 future 则只能使用固定访问。.await 和执行器负责在轮询前安排这一条件，应用代码通常不直接调用 poll。

示例

下面四个程序均用本地 rustc 1.94.0 编译并执行；它们只使用 Rust 1.98 目标版本中仍然有效的稳定 API。输出块是实际结果。

Unpin 类型的透明访问

String 实现 Unpin，所以接收 Pin<&mut String> 的函数仍可调用 get_mut()。这个例子展示的是接口兼容性，不是 String 需要地址固定。

Pin::new 可用，是因为 String: Unpin。add_status 修改字符串缓冲区的内容，但这个类型本来就不承诺依赖 String 控制块自身的地址。若函数只需要 &mut String，直接接收可变引用会更诚实；这里只是展示 Unpin 如何解除固定访问限制。

固定后建立自引用

Ticket 用 label_ptr 指向自己的 label 字段，并用 PhantomPinned 选择退出 Unpin。构造器先调用 Box::pin，然后才在一个很小的 unsafe 区域写入内部指针。

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：存储指针之前，目标已经固定。
        unsafe {
            ticket.as_mut().get_unchecked_mut().label_ptr = label_ptr;
        }
        ticket
    }

    fn label(self: Pin<&Self>) -> &str {
        // SAFETY：构造器写入了指向当前固定值内部的指针。
        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

赋值给 moved_handle 会移动 Pin<Box<Ticket>> 这个句柄，不会移动其堆上目标。安全接口不能从中取出 Ticket，因此 label_ptr 保持有效。这里使用裸指针和 unsafe 是为了展示机制；普通应用应优先使用索引、拥有型数据或已有的固定投影工具，避免自行维护自引用。

按 Future 契约轮询

Countdown 没有地址敏感字段，所以自动实现 Unpin。Future 接口仍要求固定接收者，以便同一个 trait 也能安全支持需要固定的状态机。

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")

第一次轮询减少计数并通知 waker，第二次返回结果。因为 Countdown: Unpin，字段赋值可通过 Pin 的 DerefMut 实现；若加入结构性固定字段，就需要安全投影或经过证明的 unsafe 投影。真实执行器根据唤醒通知安排下一次轮询，不会像示例一样手动连续调用。

用 Pin::set 替换固定值

Phase 因 PhantomPinned 而成为 !Unpin，但 Pin::set 仍可替换整个值。输出顺序显示旧值先完成析构，新值随后占用该位置。

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 保证先析构 queued，所以不会在地址敏感状态仍然存在时直接覆盖字节。新 Phase 之后在作用域末尾正常析构。若类型需要建立内部指针，新值仍须在替换后按自己的构造协议进入地址敏感状态，不能复用旧指针。

陷阱

把固定指针当成不可移动句柄

修复方法： 每次都区分指针值与其目标值。审查赋值时写明被移动的是 Pin<Box<T>> 句柄还是 T；真正危险的是解引用后取出、替换或复制 T 的字节。

认为 Pin 自动限制所有类型

修复方法： 先判断类型是否真的维护地址不变量。需要选择退出自动 Unpin 时使用 PhantomPinned 或依赖一个确实为 !Unpin 的字段；不要为解决普通借用错误而添加 Pin。

在固定之前创建自引用

修复方法： 使用两阶段初始化：先把所有普通字段放到最终存储位置并固定，再通过受控的 unsafe 写入内部地址。构造器应返回 Pin<Box<Self>> 等固定句柄，不要返回还能自由移动的 Self。

从 unsafe 投影泄漏可移动引用

修复方法： 把 unsafe 封装在最小的投影 API 中，逐字段记录哪些字段固定、哪些字段可移动，并审查 Drop 是否遵守同一选择。成熟宏或库可以生成投影时，应优先复用其已审查实现。

为通过约束而手写 Unpin

修复方法： 把 Unpin 约束当作 API 设计信号，先改用固定调用方式或调整泛型边界。只有证明类型在移动后仍保持全部不变量时才实现 Unpin，并用编译失败测试保护真正应为 !Unpin 的类型。

忽略析构与存储失效

修复方法： 对创建 Pin 的自定义指针审查 Deref、DerefMut 和 Drop 的行为，并让固定字段留在原位直到其析构结束。需要替换整个值时使用 Pin::set 这类保持析构顺序的安全 API。

延伸阅读

• Rust 标准库：std::pin 模块
• Rust 标准库：Pin
• Rust 标准库：Unpin
• Rust 标准库：Future
• The Rust Programming Language：Future 与 async 语法