Pin<T> ​

核心概念 ​

Pin<P> 是 Rust 标准库 std::pin 模块中的一个包装类型,它保证被包装指针 P 所指向的数据不会在内存中被移动。P 通常是 &mut T(栈上 pin)或 Box<T>(堆上 pin)。Pin 的存在主要是为了解决自引用结构的安全问题——当一个结构体内部有指针指向自身的其他字段时,如果整个结构体被移动到新的内存地址,这些内部指针就会变成悬垂指针。async fn 编译生成的状态机就可能包含这样的自引用,因此 Future::poll 方法要求 Pin<&mut Self>。

Pin 和 Unpin trait 配合工作:实现了 Unpin 的类型(大多数普通类型)即使被 Pin 也可以安全移动,Pin 对它们是透明的;没有实现 Unpin 的类型(如编译器生成的 Future)一旦被 Pin 就不能移动。

rust
use std::pin::Pin;

fn main() {
    // 基本用法:Pin 一个可变引用
    let mut value = 42;
    let pinned: Pin<&mut i32> = Pin::new(&mut value);
    // i32 是 Unpin 的,Pin 对它没有额外限制
    println!("Pin<&mut i32>: {}", *pinned);

    // Pin 一个 Box
    let boxed: Pin<Box<String>> = Box::pin(String::from("pinned string"));
    println!("Pin<Box<String>>: {}", *boxed);

    // 对于 Unpin 类型,Pin 基本上是透明的
    let mut data = vec![1, 2, 3];
    let mut pinned = Pin::new(&mut data);
    // 可以通过 get_mut 拿到 &mut T(因为 Vec 是 Unpin)
    pinned.as_mut().get_mut().push(4);
    println!("修改后: {:?}", pinned);
}

为什么需要 Pin ​

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

// 自引用结构:ptr 指向自身的 data 字段
struct SelfRef {
    data: String,
    ptr: *const String,   // 指向 self.data
    _pin: PhantomPinned,  // 标记为 !Unpin
}

impl SelfRef {
    fn new(data: &str) -> Pin<Box<Self>> {
        let s = SelfRef {
            data: data.to_string(),
            ptr: std::ptr::null(),
            _pin: PhantomPinned,
        };
        let mut boxed = Box::pin(s);

        // 设置 ptr 指向 data
        let ptr: *const String = &boxed.data;
        unsafe {
            let mut_ref = Pin::as_mut(&mut boxed);
            Pin::get_unchecked_mut(mut_ref).ptr = ptr;
        }

        boxed
    }

    fn data(&self) -> &str {
        &self.data
    }

    fn ptr_data(&self) -> &str {
        // 通过内部指针读取数据
        unsafe { &*self.ptr }
    }
}

fn main() {
    let s = SelfRef::new("hello");

    // data 和 ptr 指向同一个字符串
    println!("data: {}", s.data());
    println!("ptr:  {}", s.ptr_data());

    // 如果 s 被移动,ptr 会变成悬垂指针
    // Pin 阻止了这种移动
    // let moved = *s;  // 编译错误:不能移出 Pin<Box<T>>

    // 没有 Pin 的话,下面的操作会导致未定义行为:
    // let mut a = SelfRef { ... };
    // let mut b = SelfRef { ... };
    // std::mem::swap(&mut a, &mut b);  // a.ptr 仍然指向旧的 a.data 的位置
    // 但现在那个位置存放的是 b 的数据了!
}

Pin 的创建方式 ​

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

fn main() {
    // === Pin::new ===
    // 只能用于实现了 Unpin 的类型
    let mut x = 42_i32;
    let pinned = Pin::new(&mut x);
    println!("Pin::new: {}", *pinned);

    // === Box::pin ===
    // 适用于任何类型,将值放到堆上并 pin
    let pinned = Box::pin(String::from("heap pinned"));
    println!("Box::pin: {}", *pinned);

    // 对 !Unpin 类型只能用 Box::pin
    struct NotUnpin {
        _marker: PhantomPinned,
    }
    let _pinned = Box::pin(NotUnpin { _marker: PhantomPinned });
    // Pin::new 不能用于 !Unpin 类型
    // Pin::new(&mut NotUnpin { _marker: PhantomPinned });  // 编译错误

    // === pin! 宏(Rust 1.68+)===
    // 在栈上 pin,不需要堆分配
    let pinned = std::pin::pin!(String::from("stack pinned"));
    println!("pin!: {}", *pinned);

    // === Pin::new_unchecked (unsafe) ===
    // 对 !Unpin 类型在栈上创建 Pin
    // 调用者必须保证数据不会被移动
    let mut data = NotUnpin { _marker: PhantomPinned };
    let _pinned = unsafe { Pin::new_unchecked(&mut data) };
    // 从此刻起 data 不能被移动(由程序员保证)
}

Pin 的方法 ​

rust
use std::pin::Pin;

fn main() {
    // === as_ref / as_mut ===
    // 转换 Pin 的指针类型
    let mut value = String::from("hello");
    let mut pinned = Pin::new(&mut value);

    // Pin<&mut T> → Pin<&T>
    let pin_ref: Pin<&String> = pinned.as_ref();
    println!("as_ref: {}", *pin_ref);

    // 获取 Pin<&mut T>(重新借用)
    let pin_mut: Pin<&mut String> = pinned.as_mut();
    // 对 Unpin 类型可以 get_mut
    pin_mut.get_mut().push_str(" world");

    // === get_mut(仅 Unpin 类型)===
    let mut data = vec![1, 2, 3];
    let mut pinned = Pin::new(&mut data);
    let inner: &mut Vec<i32> = pinned.as_mut().get_mut();
    inner.push(4);
    println!("get_mut: {:?}", inner);

    // === into_inner(仅 Unpin 类型)===
    let mut x = 42;
    let pinned = Pin::new(&mut x);
    let inner: &mut i32 = Pin::into_inner(pinned);
    *inner = 100;
    println!("into_inner: {}", inner);
}
方法要求作用
Pin::new(ptr)T: Unpin创建 Pin
Box::pin(val)无堆上 Pin
pin!(val)无栈上 Pin(Rust 1.68+)
as_ref()无Pin<&mut T> → Pin<&T>
as_mut()无重新借用 Pin<&mut T>
get_mut()T: UnpinPin<&mut T> → &mut T
get_unchecked_mut()unsafe无论 Unpin 与否都获取 &mut T
into_inner()T: Unpin解开 Pin 取出指针

Pin 在异步编程中的应用 ​

rust
use std::pin::Pin;
use std::future::Future;
use tokio::time::{sleep, Duration, Instant};

// 返回 trait object 时需要 Pin<Box<dyn Future>>
fn make_future(id: u32) -> Pin<Box<dyn Future<Output = String> + Send>> {
    Box::pin(async move {
        sleep(Duration::from_millis(50 * id as u64)).await;
        format!("任务{}", id)
    })
}

// 递归 async 需要 Pin<Box>
fn fibonacci(n: u64) -> Pin<Box<dyn Future<Output = u64> + Send>> {
    Box::pin(async move {
        if n <= 1 {
            n
        } else {
            let a = fibonacci(n - 1).await;
            let b = fibonacci(n - 2).await;
            a + b
        }
    })
}

// 在集合中存储 Future
async fn run_batch(futures: Vec<Pin<Box<dyn Future<Output = String> + Send>>>) -> Vec<String> {
    futures::future::join_all(futures).await
}

#[tokio::main]
async fn main() {
    // 动态创建 Future
    let futures: Vec<_> = (1..=5).map(make_future).collect();
    let start = Instant::now();
    let results = run_batch(futures).await;
    println!("批量结果: {:?} ({:?})", results, start.elapsed());

    // 递归 async
    let fib10 = fibonacci(10).await;
    println!("fibonacci(10) = {}", fib10);

    // pin! 宏在 select! 中的使用
    let mut f1 = std::pin::pin!(async {
        sleep(Duration::from_millis(100)).await;
        "慢"
    });
    let mut f2 = std::pin::pin!(async {
        sleep(Duration::from_millis(50)).await;
        "快"
    });

    let result = tokio::select! {
        r = &mut f1 => r,
        r = &mut f2 => r,
    };
    println!("先完成: {}", result);
}

基本示例 ​

综合展示 Pin 在不同场景中的使用:

rust
use std::pin::Pin;
use std::future::Future;
use std::marker::PhantomPinned;
use tokio::time::{sleep, Duration, Instant};

// === 场景1:异步任务调度器 ===
struct AsyncScheduler {
    tasks: Vec<(String, Pin<Box<dyn Future<Output = String> + Send>>)>,
}

impl AsyncScheduler {
    fn new() -> Self {
        AsyncScheduler { tasks: Vec::new() }
    }

    fn add<F>(&mut self, name: &str, future: F)
    where
        F: Future<Output = String> + Send + 'static,
    {
        // Future 必须用 Box::pin 包装才能存储
        self.tasks.push((name.to_string(), Box::pin(future)));
    }

    async fn run(self) {
        let names: Vec<_> = self.tasks.iter().map(|(n, _)| n.clone()).collect();
        let futures: Vec<_> = self.tasks.into_iter().map(|(_, f)| f).collect();

        let results = futures::future::join_all(futures).await;

        for (name, result) in names.iter().zip(results.iter()) {
            println!("  {}: {}", name, result);
        }
    }
}

// === 场景2:Pin 保护的缓冲区 ===
struct PinnedBuffer {
    data: Vec<u8>,
    _pin: PhantomPinned,
}

impl PinnedBuffer {
    fn new(size: usize) -> Pin<Box<Self>> {
        Box::pin(PinnedBuffer {
            data: vec![0; size],
            _pin: PhantomPinned,
        })
    }

    // Pin 保证缓冲区地址不变
    fn address(self: Pin<&Self>) -> usize {
        self.data.as_ptr() as usize
    }

    fn len(self: Pin<&Self>) -> usize {
        self.data.len()
    }
}

#[tokio::main]
async fn main() {
    let start = Instant::now();

    // 场景1:异步调度器
    println!("=== 异步调度器 ===");
    let mut scheduler = AsyncScheduler::new();

    scheduler.add("数据加载", async {
        sleep(Duration::from_millis(150)).await;
        "加载完成".to_string()
    });
    scheduler.add("缓存预热", async {
        sleep(Duration::from_millis(80)).await;
        "预热完成".to_string()
    });
    scheduler.add("配置读取", async {
        sleep(Duration::from_millis(50)).await;
        "读取完成".to_string()
    });

    scheduler.run().await;
    println!("耗时: {:?}\n", start.elapsed());

    // 场景2:Pin 保护的缓冲区
    println!("=== Pin 保护的缓冲区 ===");
    let buf = PinnedBuffer::new(1024);
    let addr1 = buf.as_ref().address();
    println!("  缓冲区地址: 0x{:x}", addr1);
    println!("  缓冲区大小: {} 字节", buf.as_ref().len());
    // 缓冲区不会被移动,地址保持不变
    let addr2 = buf.as_ref().address();
    assert_eq!(addr1, addr2);
    println!("  地址不变: {}", addr1 == addr2);

    // 场景3:Pin 与 Unpin 类型的对比
    println!("\n=== Unpin vs !Unpin ===");

    // Unpin 类型:Pin 是透明的
    let mut v = vec![1, 2, 3];
    let mut pinned = Pin::new(&mut v);
    pinned.as_mut().get_mut().push(4);  // 可以自由修改
    println!("  Unpin Vec: {:?}", pinned);

    // !Unpin 类型:被 Pin 后不能移出
    let pinned_buf = PinnedBuffer::new(10);
    // let moved = *pinned_buf;  // 编译错误:不能从 Pin 中移出 !Unpin 类型
    println!("  !Unpin 缓冲区: {} 字节(不能移动)", pinned_buf.as_ref().len());

    // 场景4:动态分发的异步任务
    println!("\n=== 动态分发 ===");
    let tasks: Vec<Pin<Box<dyn Future<Output = &str> + Send>>> = vec![
        Box::pin(async { sleep(Duration::from_millis(30)).await; "A" }),
        Box::pin(async { sleep(Duration::from_millis(20)).await; "B" }),
        Box::pin(async { sleep(Duration::from_millis(10)).await; "C" }),
    ];

    let results = futures::future::join_all(tasks).await;
    println!("  结果: {:?}", results);
}

常见问题 ​

问题一:日常写异步代码需要关心 Pin 吗?

大多数时候不需要。async/await 语法隐藏了 Pin 的细节。只在以下场景需要直接用 Pin:把 Future 存到集合里(Vec<Pin<Box<dyn Future>>>)、返回 dyn Future trait object、递归 async 函数、手动实现 Future trait。

问题二:Pin 和 Box 有什么关系?

Box::pin(val) 创建 Pin<Box<T>>,先在堆上分配空间,然后 pin 住。Pin<Box<T>> 保证堆上的数据不会被移动。Box 本身是 Unpin 的(Box 可以移动),但 Pin<Box<T>> 保护的是 Box 指向的数据不移动。

问题三:PhantomPinned 有什么用?

PhantomPinned 是一个零大小的标记类型,实现了 !Unpin。在结构体中加入 PhantomPinned 字段可以让整个结构体变成 !Unpin,这样被 Pin 后就真的不能移动了。

问题四:pin! 宏和 Box::pin 怎么选?

pin! 在栈上 pin,没有堆分配开销,但 pinned 值的生命周期受限于当前作用域。Box::pin 在堆上 pin,有分配开销,但可以将 pinned 值移动到任何地方(移动的是 Box,不是数据)。需要存储或返回时用 Box::pin,临时使用时用 pin!。

适用场景 ​

  • 存储 Future:Vec<Pin<Box<dyn Future>>> 存储异步任务集合
  • 动态分发:返回 Pin<Box<dyn Future>> 类型擦除
  • 递归异步:递归 async fn 必须用 Box::pin 包装
  • 自引用结构:保护内部指针的安全性

注意事项 ​

  • Unpin 类型被 Pin 后仍可移动,Pin 对其透明
  • !Unpin 类型被 Pin 后不能移动(编译器保证)
  • Box::pin 是最安全、最常用的 pin 方式
  • pin! 宏避免堆分配但作用域受限
  • Pin::new 只能用于 Unpin 类型
  • get_unchecked_mut 是 unsafe 的,跳过 Pin 保护

总结 ​

Pin<P> 保证指针 P 指向的数据不会在内存中被移动,主要用于保护自引用结构的安全。Unpin 类型被 Pin 后仍可自由移动(Pin 透明),!Unpin 类型被 Pin 后不能移动。async fn 生成的 Future 可能是 !Unpin 的(包含自引用),所以 Future::poll 要求 Pin<&mut Self>。Box::pin 是最常用的 pin 方式,适合存储和返回 Future。pin! 宏在栈上 pin,避免堆分配。PhantomPinned 标记类型使结构体变为 !Unpin。日常 async/await 代码不需要直接使用 Pin,只在存储 Future 集合、动态分发、递归异步等场景需要。