Struct core::pin::Pin

1.33.0 · source ·

#[repr(transparent)]
pub struct Pin<P> { /* private fields */ }

Expand description

固定的指针。

这是一种指针的包装，该指针使该指针 “pin” 成为其值，从而防止该指针引用的值被移动，除非它实现 Unpin。

Pin 保证具有与 P 相同的内存布局和 ABI。

有关固定的说明，请参见 pin module 文档。

Implementations§

source §

impl<P: Deref<Target: Unpin>> Pin

const: unstable · source

pub fn new(pointer: P) -> Pin

围绕一个指向实现 Unpin 类型的数据的指针，创建一个新的 Pin。

与 Pin::new_unchecked 不同，此方法是安全的，因为指针 P 解引用了 Unpin 类型，从而取消了固定保证。

pub fn into_inner(pin: Pin) -> P

解包此 Pin，返回底层指针。

这要求此 Pin 中的数据实现 Unpin，以便我们在展开它时可以忽略固定不，变体。

impl<P: Deref> Pin

const: unstable · source

pub unsafe fn new_unchecked(pointer: P) -> Pin

围绕引用可能会或可能不会实现 Unpin 的某些数据，创建一个新的 Pin。

如果 pointer 解引用 Unpin 类型，则应改用 Pin::new。

Safety

此构造函数是不安全的，因为我们不能保证 pointer 指向的数据是固定的，这意味着在丢弃数据之前，数据将不会移动或存储空间无效。如果构造的 Pin 不能保证数据 P 指向固定的，则违反了 API 约定，并可能在以后的 (safe) 操作中导致未定义的行为。

通过使用此方法，您正在制作有关 P::Deref 和 P::DerefMut 实现的 promise (如果存在)。最重要的是，它们一定不能移出 self 参数: Pin::as_mut 和 Pin::as_ref 将调用 DerefMut::deref_mut 和 Deref::derefon the 固定指针，并期望这些方法支持固定不变性。此外，通过调用此方法，不会再移出引用 P 引用的 promise；特别是，必须不可能先获得 &mut P::Target，然后再移出该引用 (例如，使用 mem::swap)。

例如，在 &'a mut T 上调用 Pin::new_unchecked 是不安全的，因为虽然可以为给定的生命周期 'a 固定 Pin::new_unchecked，但是您无法控制 'a 结束后是否保持固定状态：

use std::mem;
use std::pin::Pin;

fn move_pinned_ref<T>(mut a: T, mut b: T) {
    unsafe {
        let p: Pin<&mut T> = Pin::new_unchecked(&mut a);
        // 这应该意味着指针 `a` 再也无法移动了。
    }
    mem::swap(&mut a, &mut b); // 潜在的 UB ⚠️
    // `a` 的地址更改为 `b` 的栈插槽，因此即使我们先前已将其固定，`a` 还是被移动了！ 我们违反了固定 API 契约。
}

Run

固定后的值必须永远固定 (除非其类型实现 Unpin)。

同样，在 Rc<T> 上调用 Pin::new_unchecked 是不安全的，因为相同数据的别名可能不受固定限制的限制：

use std::rc::Rc;
use std::pin::Pin;

fn move_pinned_rc<T>(mut x: Rc<T>) {
    let pinned = unsafe { Pin::new_unchecked(Rc::clone(&x)) };
    {
        let p: Pin<&T> = pinned.as_ref();
        // 这应该意味着指向者永远不能再移动。
    }
    drop(pinned);
    let content = Rc::get_mut(&mut x).unwrap(); // 潜在的 UB ⚠️
    // 现在，如果 `x` 是唯一的引用，则对上面固定的数据有一个变量引用，就像在上一个示例中看到的那样，我们可以使用它来移动它。
    // 我们违反了固定 API 契约。
 }

Run

闭包捕获的置顶

在闭包中使用 Pin::new_unchecked 时需要特别小心: Pin::new_unchecked(&mut var) 其中 var 是按值 (moved) 闭包捕获隐式地使闭包本身被固定的 promise，并且此闭包捕获的所有使用都尊重该固定。

use std::pin::Pin;
use std::task::Context;
use std::future::Future;

fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {
    // 创建一个移动 `x` 的闭包，然后在内部以固定的方式使用。
    let mut closure = move || unsafe {
        let _ignore = Pin::new_unchecked(&mut x).poll(cx);
    };
    // 调使用闭包，所以 future 可以假定它已被固定。
    closure();
    // 把封包移到别处。这也动了 `x`!
    let mut moved = closure;
    // 再次调用它意味着我们从两个不同的位置轮询 future，这违反了固定 API 合同。
    moved(); // 潜在的 UB ⚠️
}

Run

将闭包传递给另一个 API 时，它可能会随时移动闭包，因此仅当 API 明确记录闭包已固定时，才能使用闭包捕获上的 Pin::new_unchecked。

更好的选择是避免所有这些麻烦，而是在外部函数中固定 (这里使用 pin! 宏) :

use std::pin::pin;
use std::task::Context;
use std::future::Future;

fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {
    let mut x = pin!(x);
    // 创建一个捕获 `x: Pin<&mut _>` 的闭包，可以安全移动。
    let mut closure = move || {
        let _ignore = x.as_mut().poll(cx);
    };
    // 调使用闭包，所以 future 可以假定它已被固定。
    closure();
    // 把封包移到别处。
    let mut moved = closure;
    // 在这里再次调用它很好 (除了我们可能正在轮询一个已经返回 `Poll::Ready` 的 future，但这是一个单独的问题)。
    moved();
}

Run

source

pub fn as_ref(&self) -> Pin<&P::Target>

从此固定指针获取固定共享引用。

这是从 &Pin<Pointer<T>> 到 Pin<&T> 的通用方法。这是安全的，因为作为 Pin::new_unchecked 契约的一部分，在创建 Pin<Pointer<T>> 之后，指针无法移动。

Pointer::Deref 的 “Malicious” 实现同样被 Pin::new_unchecked 的契约排除在外。

1.39.0 (const: unstable) · source

pub unsafe fn into_inner_unchecked(pin: Pin) -> P

解包此 Pin，返回底层指针。

Safety

该函数是不安全的。您必须保证在调用此函数后，将继续将指针 P 视为固定指针，以便可以支持 Pin 类型上的不变量。如果使用生成的 P 的代码不能继续维护违反 API 约定的固定不变量，则可能会在以后的 (safe) 操作中导致未定义的行为。

如果底层数据是 Unpin，则应改为使用 Pin::into_inner。

source §

impl<P: DerefMut> Pin

source

pub fn as_mut(&mut self) -> Pin<&mut P::Target>

从此固定指针获取固定变量引用。

这是从 &mut Pin<Pointer<T>> 到 Pin<&mut T> 的通用方法。这是安全的，因为作为 Pin::new_unchecked 契约的一部分，在创建 Pin<Pointer<T>> 之后，指针无法移动。

Pointer::DerefMut 的 “Malicious” 实现同样被 Pin::new_unchecked 的契约排除在外。

当对使用固定类型的函数进行多次调用时，此方法很有用。

Example

use std::pin::Pin;

impl Type {
    fn method(self: Pin<&mut Self>) {
        // 做一点事
    }

    fn call_method_twice(mut self: Pin<&mut Self>) {
        // `method` 消耗 `self`，因此通过 `as_mut` 重新借用 `Pin<&mut Self>`。
        self.as_mut().method();
        self.as_mut().method();
    }
}

Run

source

pub fn set(&mut self, value: P::Target)where P::Target: Sized,

为固定的引用后面的内存分配一个新值。

这会覆盖固定的数据，但是没关系：它的析构函数在被覆盖之前就已运行，因此不会违反固定保证。

Example

use std::pin::Pin;

let mut val: u8 = 5;
let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
println!("{}", pinned); // 5
pinned.as_mut().set(10);
println!("{}", pinned); // 10