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 就不能移动。
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
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 的创建方式
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 的方法
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: Unpin | Pin<&mut T> → &mut T |
get_unchecked_mut() | unsafe | 无论 Unpin 与否都获取 &mut T |
into_inner() | T: Unpin | 解开 Pin 取出指针 |
Pin 在异步编程中的应用
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 在不同场景中的使用:
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 集合、动态分发、递归异步等场景需要。