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语法