//! 键入将数据固定到其在内存中的位置的类型。
//!
//! 从对象在内存中的位置不变的意义上讲，保证对象不移动有时很有用。
//! 这种情况的一个主要例子是构建自引用结构，因为移动一个带有指向自身的指针的对象会使它们无效，这可能导致未定义的行为。
//!
//! 在高层次上，<code>[Pin]\<P></code> 确保任何指针类型 `P` 的指针在内存中都有一个稳定的位置，这意味着它不能被移动到其他地方，并且它的内存不能被释放，直到它被丢弃。我们说该对象是 "pinned"。当讨论将固定数据与非固定数据结合在一起的类型时，事情变得更加微妙。[查看下文](#projections-and-structural-pinning) 了解更多详细信息。
//!
//! 默认情况下，Rust 中的所有类型都是可移动的。
//! Rust 允许按值传递所有类型，以及常见的智能指针类型，例如 <code>[Box]\<T></code> 和 <code>[&mut] T</code> 允许替换和移动它们包含的值：您可以移出 <code>[Box]\<T></code>，或者您可以使用 [`mem::swap`]。<code>[Pin]\<P></code> 包装一个指针类型 `P`，所以 <code>[Pin]<[Box]\<T>></code>函数很像一个普通的 <code>[Box]\<T></code>：
//! 当 <code>[Pin]<[Box]\<T>></code>被丢弃，其内容也被丢弃，内存被释放。类似地，<code>[Pin]<[&mut] T></code>很像 <code>[&mut] T</code>。
//! 然而，<code>[Pin]\<P></code> 不让客户实际获得 <code>[Box]\<T></code> 或 <code>[&mut] T</code> 固定数据，这意味着您不能使用 [`mem::swap`] 之类的操作：
//!
//! ```
//! use std::pin::Pin;
//! fn swap_pins<T>(x: Pin<&mut T>, y: Pin<&mut T>) {
//!     // `mem::swap` 需要 `&mut T`，但我们无法得到它。
//!     // 我们被困住了，我们不能交换这些引用的内容。
//!     // 我们可以使用 `Pin::get_unchecked_mut`，但这是不安全的，原因如下：
//!     // 我们不允许将其用于将物品移出 `Pin`。
//! }
//! ```
//!
//! 值得重申的是 <code>[Pin]\<P></code> 不会改变一个事实，即 Rust 编译器认为所有类型都是可移动的。
//! [`mem::swap`] 仍可用于任何 `T`。
//! 相反，<code>[Pin]\<P></code> 防止某些值 (由 <code>[Pin]\<P></code>) 使其无法调用需要 <code>[&mut] T</code> 方法 (如 [`mem::swap`]) 而被移动。
//!
//! <code>[Pin]\<P></code> 可用于包装任何指针类型 `P`，因此它与 [`Deref`] 和 [`DerefMut`] 交互。<code>[Pin]\<P></code>其中 <code>P: [Deref]</code> 应被视为固定 <code>P::[Target]</code>的 "`P`-style pointer" - 因此，<code>[Pin]<[Box]\<T>></code>是指向固定 `T` 的拥有指针，以及 <code>[Pin]<[Rc]\<T>></code><code>[Pin]<[Rc]\></code> 是指向固定 `T` 的引用计数指针。
//! 为正确起见，<code>[Pin]\<P></code> 依赖于 [`Deref`] 和 [`DerefMut`] 的实现不会移出它们的 `self` 参数，并且只在固定指针上调用它们时才返回指向固定数据的指针。
//!
//! # `Unpin`
//!
//! 即使不固定，许多类型也始终可以自由移动，因为它们不依赖于具有稳定的地址。这包括所有原始类型 (如 [`bool`]，[`i32`] 和引用) 以及仅由这些类型组成的类型。不关心 pinning 的类型实现了 [`Unpin`] auto-trait，取消了 <code>[Pin]\<P></code>.
//! 对于 <code>T: [Unpin]</code>, <code>[Pin]<[Box]\<T>></code>和 <code>[Box]\<T></code> 函数相同，<code>[Pin]<[&mut] T></code> 和 <code>[&mut] T</code>。
//!
//! 请注意，固定和 [`Unpin`] 仅影响指向类型 <code>P::[Target]</code>，而不影响包含在 <code>[Pin]\<P></code> 的指针类型 `P` 本身.
//! 例如，是否 <code>[Box]\<T></code> 是 [`Unpin`] 对 <code>[Pin]<[Box]\<T>></code> 的行为没有影响(这里，`T` 是指向类型)。
//!
//! # 示例：自引用结构体
//!
//! 在我们详细解释与 <code>[Pin]\</code> 相关的保证和选择之前 <code>[Pin]\<P></code>，我们讨论了一些如何使用它的例子。
//! 请随意 [跳到理论讨论的地方继续](#drop-guarantee)。
//!
//! ```rust
//! use std::pin::Pin;
//! use std::marker::PhantomPinned;
//! use std::ptr::NonNull;
//!
//! // 这是一个自引用结构体，因为切片字段指向数据字段。
//! // 我们无法通过正常的引用将其告知编译器，因为无法使用通常的借用规则来描述此模式。
//! //
//! // 取而代之的是，我们使用一个裸指针，尽管我们知道它指向的是一个不为 null 的指针。
//! //
//! struct Unmovable {
//!     data: String,
//!     slice: NonNull<String>,
//!     _pin: PhantomPinned,
//! }
//!
//! impl Unmovable {
//!     // 为了确保函数返回时数据不会移动，我们将其放置在堆中，以保留对象的生命周期，唯一的访问方法是通过指向它的指针。
//!     //
//!     //
//!     fn new(data: String) -> Pin<Box<Self>> {
//!         let res = Unmovable {
//!             data,
//!             // 我们仅在数据到位后创建指针，否则数据将在我们开始之前就已经移动
//!             //
//!             slice: NonNull::dangling(),
//!             _pin: PhantomPinned,
//!         };
//!         let mut boxed = Box::pin(res);
//!
//!         let slice = NonNull::from(&boxed.data);
//!         // 我们知道这是安全的，因为修改字段不会移动整个结构体
//!         unsafe {
//!             let mut_ref: Pin<&mut Self> = Pin::as_mut(&mut boxed);
//!             Pin::get_unchecked_mut(mut_ref).slice = slice;
//!         }
//!         boxed
//!     }
//! }
//!
//! let unmoved = Unmovable::new("hello".to_string());
//! // 只要结构体没有移动，指针应指向正确的位置。
//! //
//! // 同时，我们可以随意移动指针。
//! # #[allow(unused_mut)]
//! let mut still_unmoved = unmoved;
//! assert_eq!(still_unmoved.slice, NonNull::from(&still_unmoved.data));
//!
//! // 由于我们的类型未实现 Unpin，因此无法编译：
//! // let mut new_unmoved = Unmovable::new("world".to_string());
//! // std::mem::swap(&mut *still_unmoved, &mut *new_unmoved);
//! ```
//!
//! # 示例：侵入式双向链表列表
//!
//! 在侵入式双向链表中，集合实际上并未为元素本身分配内存。
//! 分配由客户端控制，元素可以驻留在比集合短的栈框架上。
//!
//! 为了使此工作有效，列表中的每个元素都有指向其前任和后任的指针。元素只能在固定时添加，因为四处移动元素会使指针无效。此外，链表元素的 [`Drop`][Drop] 实现将修补其前任和后继的指针以将其从列表中删除。
//!
//! 至关重要的是，我们必须能够依靠被调用的 [`drop`]。如果在不调用 [`drop`] 的情况下可以释放元素或使元素无效，则来自其相邻元素的指针将变为无效，这将破坏数据结构体。
//!
//! 因此，固定还会附带 [丢弃][drop] 相关的保证。
//!
//! # `Drop` 保证
//!
//! 固定的目的是能够依靠某些数据在内存中的放置。
//! 为了使这项工作有效，不仅限制了移动数据，还限制了数据的传输。限制用于存储数据的内存的重新分配，重新分配用途或以其他方式使之无效。
//! 具体来说，对于固定的数据，必须保持不变，即从固定 *its memory 到调用 [`drop`]*，*its memory 都不会失效或重新使用。只有 [`drop`] 返回或 panics，才可以重用该内存。
//!
//! 内存可以通过释放为 "invalidated"，也可以通过将 <code>[Some]\(v)</code> 替换为 [`None`]，或将 vector 中的某些元素从 [`Vec::set_len`] 调用到 "kill"。可以通过使用 [`ptr::write`] 覆盖它来重新利用它，而无需先调用析构函数。在不调用 [`drop`] 的情况下，不允许对固定数据进行任何此操作。
//!
//! 这正是上一节中的侵入式链表需要正确执行函数的一种保证。
//!
//! 请注意，此保证不代表内存不会泄漏！ 永远不要在固定元素上调用 [`drop`] 仍然是完全可以的 (例如，您仍然可以在 <code>[Pin]<[Box]\<T>></code>)。在双向链表的示例中，该元素将仅保留在列表中。但是，您不得释放或重用调用 [`drop`]* 的存储 *without。
//!
//! # `Drop` 实现
//!
//! 如果您的类型使用固定 (例如上面的两个示例)，则在实现 [`Drop`][Drop] 时必须小心。[`drop`] 函数采用 <code>[&mut] self</code>，但这被称为即使您的类型之前已固定！</code> 好像编译器自动调用了 [`Pin::get_unchecked_mut`]。
//!
//! 这绝不会导致安全代码出现问题，因为实现依赖于固定的类型需要不安全的代码，但请注意，决定在您的类型中使用固定 (例如通过在 <code>[Pin]<[&]Self></code> 或 <code>[Pin]<[&mut] Self></code> 上实现某些操作) 会对您的 [`Drop`][Drop] 实现也是如此: 如果您的类型的元素可以被固定，您必须将 [`Drop`][Drop] 视为隐式采用 <code>[Pin]<[&mut] Self></code>。
//!
//!
//! 例如，您可以按如下方式实现 [`Drop`][Drop]：
//!
//! ```rust,no_run
//! # use std::pin::Pin;
//! # struct Type { }
//! impl Drop for Type {
//!     fn drop(&mut self) {
//!         // `new_unchecked` 可以，因为我们知道这个值在被丢弃后再也不会使用了。
//!         //
//!         inner_drop(unsafe { Pin::new_unchecked(self)});
//!         fn inner_drop(this: Pin<&mut Type>) {
//!             // 实际丢弃的代码在此处。
//!         }
//!     }
//! }
//! ```
//!
//! 函数 `inner_drop` 具有 *应该* 具有 [`drop`] 的类型，因此可以确保您不会以与固定冲突的方式意外使用 `self`/`this`。
//!
//! 此外，如果您的类型是 `#[repr(packed)]`，则编译器将自动移动字段以将其删除。它甚至可以对恰好足够对齐的字段执行此操作。因此，您不能使用 `#[repr(packed)]` 类型的固定。
//!
//! # 投影和结构固定
//!
//! 在使用固定结构体时，问题是如何在只需要 <code>[Pin]<[&mut] 结构体></code> 的方法中访问该结构体的字段。
//! 通常的方法是编写辅助方法 (所谓的 *projections*)，将 <code>[Pin]<[&mut] 结构体></code> 转换为对字段的引用，但该引用应该具有什么类型？ 是 <code>[Pin]<[&mut] Field></code> 还是 <code>[&mut] Field</code>?
//! `enum` 的字段以及在考虑 container/wrapper 类型 (例如 <code>[Vec]\<T></code>, <code>[Box]\<T></code>，或 <code>[RefCell]\<T></code>.
//! (此问题适用于可变引用和共享引用，我们仅在此处使用可变引用的更常见情况进行说明。)
//!
//! 事实证明，实际上是由数据结构的作者决定特定字段的固定 projection 是将 <code>[Pin]<[&mut] 结构体 ></code> 转换为 <code>[Pin]<[&mut] Field></code> 或 <code>[&mut] Field</code>.但是有一些约束，最重要的约束是 *consistency*：
//! 每个字段都可以 *或者* 投影到固定的引用，或者 * 可以删除固定作为投影的一部分。
//! 如果两者都是针对同一个字段进行的，那很可能是不合理的！
//!
//! 作为数据结构体的作者，您可以为每个字段决定是否将 "propagates" 固定到该字段。
//! 传播的固定也称为 "structural"，因为它遵循该类型的结构体。
//! 在以下各小节中，我们描述了两种选择都必须考虑的因素。
//!
//! ## Pinning 不是用于结构体的 `field`
//!
//! 固定结构体的字段可能不被固定似乎违反直觉，但这实际上是最简单的选择：如果从未创建 <code>[Pin]<[&mut] Field></code> 则不会出错！ 因此，如果您确定某个字段不具有结构固定，则只需确保您从未创建对该字段的固定引用即可。
//!
//! 没有结构固定的字段可能具有将 <code>[Pin]<[&mut] 结构体 ></code> 转换为 <code>[&mut] Field</code> 的 projection 方法:
//!
//! ```rust,no_run
//! # use std::pin::Pin;
//! # type Field = i32;
//! # struct Struct { field: Field }
//! impl Struct {
//!     fn pin_get_field(self: Pin<&mut Self>) -> &mut Field {
//!         // 可以，因为 `field` 从未被视为固定。
//!         unsafe { &mut self.get_unchecked_mut().field }
//!     }
//! }
//! ```
//!
//! 您也可以 <code>impl [Unpin] for Struct</code> 即使 `field` 的类型不是 [`Unpin`]. 当没有创建 <code>[Pin]<[&mut] Field></code>时，该类型对固定的看法 <code>[Pin]<[&mut] Field></code>。
//!
//! ## Pinning 是结构体的 `field`
//!
//! 另一个选择是确定钉扎是 `field` 还是 `field`，这意味着如果钉扎结构体，则字段也钉扎。
//!
//! 这允许编写一个创建 <code>[Pin]<[&mut] Field></code> 的 projection，从而见证该字段被固定：
//!
//! ```rust,no_run
//! # use std::pin::Pin;
//! # type Field = i32;
//! # struct Struct { field: Field }
//! impl Struct {
//!     fn pin_get_field(self: Pin<&mut Self>) -> Pin<&mut Field> {
//!         // 可以，因为 `self` 固定在 `field` 上。
//!         unsafe { self.map_unchecked_mut(|s| &mut s.field) }
//!     }
//! }
//! ```
//!
//! 但是，结构固定需要一些额外的要求：
//!
//! 1. 如果所有结构字段均为 [`Unpin`]，则结构体必须仅为 [`Unpin`]。这是默认值，但 [`Unpin`] 是一个安全的 trait，因此作为结构体的作者，您有责任*不*添加类似 <code>impl\[Unpin] for 结构体 \<T></code>. (请注意，添加投影操作需要不安全的代码，因此 [`Unpin`] 是安全的 trait 的事实并没有破坏您只需要在使用 [`unsafe`] 时担心任何这些的原则。)
//! 2. 结构体的析构函数不得将结构域移出其参数。这正是 [上一节][drop-impl] 中提出的要点: [`drop`] 采用 <code>[&mut] self</code>，但是结构体 (以及它的字段) 之前可能已经被固定了. 您必须保证不会在您的 [`Drop`][Drop] 实现中移动任何字段。特别是，如前所述，这意味着您的结构体 *不能* 为 `#[repr(packed)]`。
//!     有关如何编写 [`drop`] 的方法，请参见该部分，以使编译器可以帮助您避免意外破坏固定。
//! 3. 您必须确保遵守使用 [`Drop` 保证][drop-guarantee]：
//!     一旦固定了您的结构体，包含内容的内存就不会被覆盖或释放，而无需调用内容的析构函数。
//!     这可能很棘手，正如 <code>[VecDeque]\<T></code> 的析构函数 <code>[VecDeque]\<T></code>, 如果析构函数 panics 之一，则可能无法在所有元素上调用 [`drop`]。这违反了 [`Drop`][Drop] 保证，因为它可能导致元素在没有调用析构函数的情况下被释放。
//!     (<code>[VecDeque]\<T></code> 没有固定 projection，所以这不会导致不稳定。)
//! 4. 固定类型时，不得提供可能导致数据移出结构字段的任何其他操作。例如，如果结构体包含一个 <code>[Option]\<T></code>并且有一个类似 [`take`][Option::take] 的操作，类型为 <code>fn ([Pin]<[&mut] 结构体 \>) -> [Option]\<T></code> <code>fn ([Pin]<[&mut] 结构体 \>) -> [Option]\<T></code>，该操作可用于将 `T` 从固定的 `Struct<T>` 中移出 - 这意味着固定不能对保存此数据的字段进行结构化。
//!
//!     有关将数据移出固定类型的更复杂示例，请想象如果 <code>[RefCell]\<T></code>有一个方法 <code>fn get_pin_mut(self: [Pin]<[&mut] Self>) -> [Pin]<[&mut] T></code>。
//!     然后，我们可以执行以下操作：
//!
//!     ```compile_fail
//!     fn exploit_ref_cell<T>(rc: Pin<&mut RefCell<T>>) {
//!         { let p = rc.as_mut().get_pin_mut(); } // 在这里，我们可以固定访问 `T`。
//!         let rc_shr: &RefCell<T> = rc.into_ref().get_ref();
//!         let b = rc_shr.borrow_mut();
//!         let content = &mut *b; // 这里我们有 `&mut T` 到相同的数据。
//!     }
//!     ```
//!
//!     这是灾难性的，这意味着我们可以先固定 <code>[RefCell]\<T></code> (使用 <code>[RefCell]::get_pin_mut</code> ) 然后使用我们稍后获得的 <code>[RefCell]::get_pin_mut</code> 引用移动该内容。
//!
//! ## Examples
//!
//! 对于像 <code>[Vec]\<T></code> 这样的类型，两种可能性 (结构固定与否) 都有意义。<code>[Vec]\<T></code> 使用结构固定可以有 `get_pin`/`get_pin_mut` 方法来固定引用到元素。但是，它可能*不允许*在固定的 <code>[Vec]\<T></code> 上调用 [`pop`][Vec::pop]因为那会移动 (结构固定的) 内容！ 它也不允许 [`push`][Vec::push]，它可能会重新分配并因此也移动内容。
//!
//! <code>[Vec]\<T></code>没有结构固定可以 <code>impl\[Unpin] for [Vec]\<T></code> <code>impl\[Unpin] for [Vec]\<T></code>，因为内容永远不会被固定并且 <code>[Vec]\<T></code> 本身也可以移动。
//! 那时，固定对 vector 完全没有影响。
//!
//! 在标准库中，指针类型通常不具有结构固定，因此它们不提供固定投影。这就是为什么 <code>[Box]\<T>: [Unpin]</code> 适用于所有 `T`。对指针类型这样做是有意义的，因为移动 <code>[Box]\<T></code> 实际上并没有移动 `T`: <code>[Box]\<T></code> 即使 `T` 不是，也可以自由移动 (又名 [`Unpin`])。
//! 事实上，即使 <code>[Pin]<[Box]\<T>></code>和 <code>[Pin]<[&mut] T></code> 总是 [`Unpin`] 本身，原因相同：
//! 它们的内容 (`T`) 是固定的，但指针本身可以在不移动固定数据的情况下移动。
//! 对于 <code>[Box]\<T></code> 和 <code>[Pin]<[Box]\<T>></code>，内容是否固定完全独立于指针是否固定，意味着固定是*非*结构的。
//!
//! 当实现 [`Future`] 组合器时，通常需要对嵌套的 futures 进行结构钉扎，因为您需要将引用的钉扎到 [`poll`] 上。
//! 但是，如果您的组合器包含任何其他不需要固定的数据，您可以使这些字段不是结构化的，因此即使您只有 <code>[Pin]<[&mut] Self></code> (例如在您自己的 [`poll`] 实现中)。
//!
//! [Deref]: crate::ops::Deref "ops::Deref"
//! [`Deref`]: crate::ops::Deref "ops::Deref"
//! [Target]: crate::ops::Deref::Target "ops::Deref::Target"
//! [`DerefMut`]: crate::ops::DerefMut "ops::DerefMut"
//! [`mem::swap`]: crate::mem::swap "mem::swap"
//! [`mem::forget`]: crate::mem::forget "mem::forget"
//! [Vec]: ../../std/vec/struct.Vec.html "Vec"
//! [`Vec::set_len`]: ../../std/vec/struct.Vec.html#method.set_len "Vec::set_len"
//! [Box]: ../../std/boxed/struct.Box.html "Box"
//! [Vec::pop]: ../../std/vec/struct.Vec.html#method.pop "Vec::pop"
//! [Vec::push]: ../../std/vec/struct.Vec.html#method.push "Vec::push"
//! [Rc]: ../../std/rc/struct.Rc.html "rc::Rc"
//! [RefCell]: crate::cell::RefCell "cell::RefCell"
//! [`drop`]: Drop::drop
//! [VecDeque]: ../../std/collections/struct.VecDeque.html "collections::VecDeque"
//! [`ptr::write`]: crate::ptr::write "ptr::write"
//! [`Future`]: crate::future::Future "future::Future"
//! [drop-impl]: #drop-implementation
//! [drop-guarantee]: #drop-guarantee
//! [`poll`]: crate::future::Future::poll "future::Future::poll"
//! [&]: reference "shared reference"
//! [&mut]: reference "mutable reference"
//! [`unsafe`]: ../../std/keyword.unsafe.html "keyword unsafe"
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "pin", since = "1.33.0")]

use crate::cmp::{self, PartialEq, PartialOrd};
use crate::fmt;
use crate::hash::{Hash, Hasher};
use crate::marker::{Sized, Unpin};
use crate::ops::{CoerceUnsized, Deref, DerefMut, DispatchFromDyn, Receiver};

/// 固定的指针。
///
/// 这是一种指针的包装，该指针使该指针 "pin" 成为其值，从而防止该指针引用的值被移动，除非它实现 [`Unpin`]。
///
///
/// `Pin<P>` 保证具有与 `P` 相同的内存布局和 ABI。
///
/// *有关固定的说明，请参见 [`pin` module] 文档。*
///
/// [`pin` module]: self
///
// Note: 下面的 `Clone` 派生导致不完善，因为可以为可变引用实现 `Clone`。
//
// 有关更多详细信息，请参见 <https://internals.rust-lang.org/t/unsoundness-in-pin/11311>。
//
#[stable(feature = "pin", since = "1.33.0")]
#[lang = "pin"]
#[fundamental]
#[repr(transparent)]
#[derive(Copy, Clone)]
pub struct Pin<P> {
    // FIXME(#93176): 将此字段设为 `#[unstable] #[doc(hidden)] pub` 以:
    //   - 阻止下游用户访问它 (这将是不合理的！)，
    //   - 让 `pin!` 宏访问它 (这样的宏需要使用结构体字面量语法才能从生命周期扩展中受益)。
    //
    // 长期来看，`unsafe` 领域或宏卫生有望提供更强大的替代方案。
    #[unstable(feature = "unsafe_pin_internals", issue = "none")]
    #[doc(hidden)]
    pub pointer: P,
}

// 为了避免出现健全性问题，没有实现以下实现。
// 不受信任的 trait 实现不应访问 `&self.pointer`。
//
// 有关更多详细信息，请参见 <https://internals.rust-lang.org/t/unsoundness-in-pin/11311/73>。
//

#[stable(feature = "pin_trait_impls", since = "1.41.0")]
impl<P: Deref, Q: Deref> PartialEq<Pin<Q>> for Pin<P>
where
    P::Target: PartialEq<Q::Target>,
{
    fn eq(&self, other: &Pin<Q>) -> bool {
        P::Target::eq(self, other)
    }

    fn ne(&self, other: &Pin<Q>) -> bool {
        P::Target::ne(self, other)
    }
}

#[stable(feature = "pin_trait_impls", since = "1.41.0")]
impl<P: Deref<Target: Eq>> Eq for Pin<P> {}

#[stable(feature = "pin_trait_impls", since = "1.41.0")]
impl<P: Deref, Q: Deref> PartialOrd<Pin<Q>> for Pin<P>
where
    P::Target: PartialOrd<Q::Target>,
{
    fn partial_cmp(&self, other: &Pin<Q>) -> Option<cmp::Ordering> {
        P::Target::partial_cmp(self, other)
    }

    fn lt(&self, other: &Pin<Q>) -> bool {
        P::Target::lt(self, other)
    }

    fn le(&self, other: &Pin<Q>) -> bool {
        P::Target::le(self, other)
    }

    fn gt(&self, other: &Pin<Q>) -> bool {
        P::Target::gt(self, other)
    }

    fn ge(&self, other: &Pin<Q>) -> bool {
        P::Target::ge(self, other)
    }
}

#[stable(feature = "pin_trait_impls", since = "1.41.0")]
impl<P: Deref<Target: Ord>> Ord for Pin<P> {
    fn cmp(&self, other: &Self) -> cmp::Ordering {
        P::Target::cmp(self, other)
    }
}

#[stable(feature = "pin_trait_impls", since = "1.41.0")]
impl<P: Deref<Target: Hash>> Hash for Pin<P> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        P::Target::hash(self, state);
    }
}

impl<P: Deref<Target: Unpin>> Pin<P> {
    /// 围绕一个指向实现 [`Unpin`] 类型的数据的指针，创建一个新的 `Pin<P>`。
    ///
    /// 与 `Pin::new_unchecked` 不同，此方法是安全的，因为指针 `P` 解引用了 [`Unpin`] 类型，从而取消了固定保证。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::pin::Pin;
    ///
    /// let mut val: u8 = 5;
    /// // 我们可以固定这个值，因为它不关心被移动
    /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
    /// ```
    ///
    #[inline(always)]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin", since = "1.33.0")]
    pub const fn new(pointer: P) -> Pin<P> {
        // SAFETY: 指向的值是 `Unpin`，因此对固定没有要求。
        //
        unsafe { Pin::new_unchecked(pointer) }
    }

    /// 解包此 `Pin<P>`，返回底层指针。
    ///
    /// 这要求此 `Pin` 中的数据实现 [`Unpin`]，以便我们在展开它时可以忽略固定不，变体。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::pin::Pin;
    ///
    /// let mut val: u8 = 5;
    /// let pinned: Pin<&mut u8> = Pin::new(&mut val);
    /// // 解开引脚以获得对值的引用
    /// let r = Pin::into_inner(pinned);
    /// assert_eq!(*r, 5);
    /// ```
    #[inline(always)]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin_into_inner", since = "1.39.0")]
    pub const fn into_inner(pin: Pin<P>) -> P {
        pin.pointer
    }
}

impl<P: Deref> Pin<P> {
    /// 围绕引用可能会或可能不会实现 `Unpin` 的某些数据，创建一个新的 `Pin<P>`。
    ///
    /// 如果 `pointer` 解引用 `Unpin` 类型，则应改用 `Pin::new`。
    ///
    /// # Safety
    ///
    /// 此构造函数是不安全的，因为我们不能保证 `pointer` 指向的数据是固定的，这意味着在丢弃数据之前，数据将不会移动或存储空间无效。
    /// 如果构造的 `Pin<P>` 不能保证数据 `P` 指向固定的，则违反了 API 约定，并可能在以后的 (safe) 操作中导致未定义的行为。
    ///
    /// 通过使用此方法，您正在制作有关 `P::Deref` 和 `P::DerefMut` 实现的 promise (如果存在)。
    /// 最重要的是，它们一定不能移出 `self` 参数: `Pin::as_mut` 和 `Pin::as_ref` 将调用 `DerefMut::deref_mut` 和 `Deref::deref`*on 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 契约。
    /////
    /// }
    /// ```
    ///
    /// 固定后的值必须永远固定 (除非其类型实现 `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 契约。
    /////
    ///  }
    ///  ```
    ///
    /// ## 闭包捕获的置顶
    ///
    /// 在闭包中使用 `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 ⚠️
    /// }
    /// ```
    ///
    /// 将闭包传递给另一个 API 时，它可能会随时移动闭包，因此仅当 API 明确记录闭包已固定时，才能使用闭包捕获上的 `Pin::new_unchecked`。
    ///
    /// 更好的选择是避免所有这些麻烦，而是在外部函数中固定 (这里使用 [`pin!`][crate::pin::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();
    /// }
    /// ```
    ///
    /// [`mem::swap`]: crate::mem::swap
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[lang = "new_unchecked"]
    #[inline(always)]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin", since = "1.33.0")]
    pub const unsafe fn new_unchecked(pointer: P) -> Pin<P> {
        Pin { pointer }
    }

    /// 从此固定指针获取固定共享引用。
    ///
    /// 这是从 `&Pin<Pointer<T>>` 到 `Pin<&T>` 的通用方法。
    /// 这是安全的，因为作为 `Pin::new_unchecked` 契约的一部分，在创建 `Pin<Pointer<T>>` 之后，指针无法移动。
    ///
    /// `Pointer::Deref` 的 "Malicious" 实现同样被 `Pin::new_unchecked` 的契约排除在外。
    ///
    #[stable(feature = "pin", since = "1.33.0")]
    #[inline(always)]
    pub fn as_ref(&self) -> Pin<&P::Target> {
        // SAFETY: 请参见此函数的文档
        unsafe { Pin::new_unchecked(&*self.pointer) }
    }

    /// 解包此 `Pin<P>`，返回底层指针。
    ///
    /// # Safety
    ///
    /// 该函数是不安全的。您必须保证在调用此函数后，将继续将指针 `P` 视为固定指针，以便可以支持 `Pin` 类型上的不变量。
    /// 如果使用生成的 `P` 的代码不能继续维护违反 API 约定的固定不变量，则可能会在以后的 (safe) 操作中导致未定义的行为。
    ///
    ///
    /// 如果底层数据是 [`Unpin`]，则应改为使用 [`Pin::into_inner`]。
    ///
    ///
    ///
    ///
    #[inline(always)]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin_into_inner", since = "1.39.0")]
    pub const unsafe fn into_inner_unchecked(pin: Pin<P>) -> P {
        pin.pointer
    }
}

impl<P: DerefMut> Pin<P> {
    /// 从此固定指针获取固定变量引用。
    ///
    /// 这是从 `&mut Pin<Pointer<T>>` 到 `Pin<&mut T>` 的通用方法。
    /// 这是安全的，因为作为 `Pin::new_unchecked` 契约的一部分，在创建 `Pin<Pointer<T>>` 之后，指针无法移动。
    ///
    /// `Pointer::DerefMut` 的 "Malicious" 实现同样被 `Pin::new_unchecked` 的契约排除在外。
    ///
    /// 当对使用固定类型的函数进行多次调用时，此方法很有用。
    ///
    /// # Example
    ///
    /// ```
    /// use std::pin::Pin;
    ///
    /// # struct Type {}
    /// 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();
    ///     }
    /// }
    /// ```
    ///
    #[stable(feature = "pin", since = "1.33.0")]
    #[inline(always)]
    pub fn as_mut(&mut self) -> Pin<&mut P::Target> {
        // SAFETY: 请参见此函数的文档
        unsafe { Pin::new_unchecked(&mut *self.pointer) }
    }

    /// 为固定的引用后面的内存分配一个新值。
    ///
    /// 这会覆盖固定的数据，但是没关系：它的析构函数在被覆盖之前就已运行，因此不会违反固定保证。
    ///
    ///
    /// # 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
    /// ```
    #[stable(feature = "pin", since = "1.33.0")]
    #[inline(always)]
    pub fn set(&mut self, value: P::Target)
    where
        P::Target: Sized,
    {
        *(self.pointer) = value;
    }
}

impl<'a, T: ?Sized> Pin<&'a T> {
    /// 通过映射内部值创建一个新的引脚。
    ///
    /// 例如，如果您想获得某个字段的 `Pin`，您可以使用它在一行代码中访问该字段。
    /// 但是，这些 "pinning projections" 有一些陷阱。
    /// 有关该主题的更多详细信息，请参见 [`pin` module] 文档。
    ///
    /// # Safety
    ///
    /// 该函数是不安全的。
    /// 您必须确保只要参数值不移动，返回的数据就不会移动 (例如，因为它是该值的字段之一)，并且还必须确保不会将其移出接收到的参数内部功能。
    ///
    ///
    /// [`pin` module]: self#projections-and-structural-pinning
    ///
    ///
    #[stable(feature = "pin", since = "1.33.0")]
    pub unsafe fn map_unchecked<U, F>(self, func: F) -> Pin<&'a U>
    where
        U: ?Sized,
        F: FnOnce(&T) -> &U,
    {
        let pointer = &*self.pointer;
        let new_pointer = func(pointer);

        // SAFETY: 调用者必须遵守 `new_unchecked` 的安全保证。
        //
        unsafe { Pin::new_unchecked(new_pointer) }
    }

    /// 从 pin 中获取共享引用。
    ///
    /// 这是安全的，因为不可能移出共享引用。
    /// 内部可变性似乎存在问题：实际上，可以将 `T` 从 `&RefCell<T>` 中移出。
    /// 但是，只要不存在指向相同数据的 `Pin<&T>`，并且 `RefCell<T>` 不允许您创建对其内容的固定引用，这也不是问题。
    ///
    /// 有关更多详细信息，请参见 ["pinning projections"] 上的讨论。
    ///
    /// Note: `Pin` 还对目标实现 `Deref`，可用于访问内部值。
    /// 但是，`Deref` 仅提供一个引用，该引用的生命周期与 `Pin` 的借用时间一样长，而不是 `Pin` 本身的生命周期。
    /// 这种方法可以将 `Pin` 转换为引用，并具有与原始 `Pin` 相同的生命周期。
    ///
    /// ["pinning projections"]: self#projections-and-structural-pinning
    ///
    ///
    ///
    ///
    #[inline(always)]
    #[must_use]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin", since = "1.33.0")]
    pub const fn get_ref(self) -> &'a T {
        self.pointer
    }
}

impl<'a, T: ?Sized> Pin<&'a mut T> {
    /// 将此 `Pin<&mut T>` 转换为具有相同生命周期的 `Pin<&T>`。
    #[inline(always)]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    #[stable(feature = "pin", since = "1.33.0")]
    pub const fn into_ref(self) -> Pin<&'a T> {
        Pin { pointer: self.pointer }
    }

    /// 获取对此 `Pin` 内部数据的可变引用。
    ///
    /// 这要求该 `Pin` 内部的数据为 `Unpin`。
    ///
    /// Note: `Pin` 还对数据实现 `DerefMut`，可用于访问内部值。
    /// 但是，`DerefMut` 仅提供一个引用，该引用生命周期与 `Pin` 的借用时间一样长，而不是 `Pin` 本身的生命周期。
    ///
    /// 这种方法可以将 `Pin` 转换为引用，并具有与原始 `Pin` 相同的生命周期。
    ///
    #[inline(always)]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "pin", since = "1.33.0")]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    pub const fn get_mut(self) -> &'a mut T
    where
        T: Unpin,
    {
        self.pointer
    }

    /// 获取对此 `Pin` 内部数据的可变引用。
    ///
    /// # Safety
    ///
    /// 该函数是不安全的。
    /// 您必须保证在调用此函数时，永远不会将数据移出您收到的可变引用，以便可以支持 `Pin` 类型的不变量。
    ///
    ///
    /// 如果底层数据是 `Unpin`，则应改用 `Pin::get_mut`。
    ///
    #[inline(always)]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "pin", since = "1.33.0")]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    pub const unsafe fn get_unchecked_mut(self) -> &'a mut T {
        self.pointer
    }

    /// 通过映射内部值创建一个新的引脚。
    ///
    /// 例如，如果您想获得某个字段的 `Pin`，您可以使用它在一行代码中访问该字段。
    /// 但是，这些 "pinning projections" 有一些陷阱。
    /// 有关该主题的更多详细信息，请参见 [`pin` module] 文档。
    ///
    /// # Safety
    ///
    /// 该函数是不安全的。
    /// 您必须确保只要参数值不移动，返回的数据就不会移动 (例如，因为它是该值的字段之一)，并且还必须确保不会将其移出接收到的参数内部功能。
    ///
    ///
    /// [`pin` module]: self#projections-and-structural-pinning
    ///
    ///
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "pin", since = "1.33.0")]
    pub unsafe fn map_unchecked_mut<U, F>(self, func: F) -> Pin<&'a mut U>
    where
        U: ?Sized,
        F: FnOnce(&mut T) -> &mut U,
    {
        // SAFETY: 调用者负责不将值移出该引用。
        //
        let pointer = unsafe { Pin::get_unchecked_mut(self) };
        let new_pointer = func(pointer);
        // SAFETY: 由于保证 `this` 的值不会被移出，因此对 `new_unchecked` 的调用是安全的。
        //
        unsafe { Pin::new_unchecked(new_pointer) }
    }
}

impl<T: ?Sized> Pin<&'static T> {
    /// 从固定引用中获取固定引用。
    ///
    /// 这是安全的，因为 `T` 是 `'static` 生命周期的借用，而生命周期永远不会结束。
    ///
    #[stable(feature = "pin_static_ref", since = "1.61.0")]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    pub const fn static_ref(r: &'static T) -> Pin<&'static T> {
        // SAFETY: 静态借用保证数据在被丢弃之前不会被移动/失效 (永远不会)。
        //
        unsafe { Pin::new_unchecked(r) }
    }
}

impl<'a, P: DerefMut> Pin<&'a mut Pin<P>> {
    /// 从此嵌套的固定指针获取固定的可变引用。
    ///
    /// 这是从 `Pin<&mut Pin<Pointer<T>>>` 到 `Pin<&mut T>` 的泛型方法。
    /// 它是安全的，因为 `Pin<Pointer<T>>` 的存在确保了指向者 `T` 在 future 中不能移动，并且该方法不会使指向者移动。
    ///
    /// `P::DerefMut` 的 "Malicious" 实现同样被 `Pin::new_unchecked` 的契约排除在外。
    ///
    #[unstable(feature = "pin_deref_mut", issue = "86918")]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[inline(always)]
    pub fn as_deref_mut(self) -> Pin<&'a mut P::Target> {
        // SAFETY: 我们在这里断言的是，从
        //
        //     Pin<&mut Pin<P>>
        //
        // to
        //
        //     Pin<&mut P::Target>
        //
        // 是安全的。
        //
        // 我们需要确保有两件事能够做到这一点：
        //
        // 1) 一旦我们发出 `Pin<&mut P::Target>`，就不会发出 `&mut P::Target`。
        // 2) 通过发放 `Pin<&mut P::Target>`，我们没有违反 `Pin<&mut Pin<P>>` 的风险
        //
        // `Pin<P>` 的存在足以保证 #1: 因为我们已经有了 `Pin<P>`，它必须已经维护了固定保证，这意味着 `Pin<&mut P::Target>` 也可以，因为 `Pin::as_mut` 是安全的。
        // 我们不必依赖 P 也被固定的事实。
        //
        // 对于 #2，我们需要确保给定 `Pin<&mut P::Target>` 的代码不会导致 `Pin<P>` 移动？ 这是不可能的，因为 `Pin<&mut P::Target>` 不再保留对 `P` 本身的任何访问权限，更不用说 `Pin<P>`。
        //
        //
        //
        //
        unsafe { self.get_unchecked_mut() }.as_mut()
    }
}

impl<T: ?Sized> Pin<&'static mut T> {
    /// 从静态变量引用中获取固定的变量引用。
    ///
    /// 这是安全的，因为 `T` 是 `'static` 生命周期的借用，而生命周期永远不会结束。
    ///
    #[stable(feature = "pin_static_ref", since = "1.61.0")]
    #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
    pub const fn static_mut(r: &'static mut T) -> Pin<&'static mut T> {
        // SAFETY: 静态借用保证数据在被丢弃之前不会被移动/失效 (永远不会)。
        //
        unsafe { Pin::new_unchecked(r) }
    }
}

#[stable(feature = "pin", since = "1.33.0")]
impl<P: Deref> Deref for Pin<P> {
    type Target = P::Target;
    fn deref(&self) -> &P::Target {
        Pin::get_ref(Pin::as_ref(self))
    }
}

#[stable(feature = "pin", since = "1.33.0")]
impl<P: DerefMut<Target: Unpin>> DerefMut for Pin<P> {
    fn deref_mut(&mut self) -> &mut P::Target {
        Pin::get_mut(Pin::as_mut(self))
    }
}

#[unstable(feature = "receiver_trait", issue = "none")]
impl<P: Receiver> Receiver for Pin<P> {}

#[stable(feature = "pin", since = "1.33.0")]
impl<P: fmt::Debug> fmt::Debug for Pin<P> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&self.pointer, f)
    }
}

#[stable(feature = "pin", since = "1.33.0")]
impl<P: fmt::Display> fmt::Display for Pin<P> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.pointer, f)
    }
}

#[stable(feature = "pin", since = "1.33.0")]
impl<P: fmt::Pointer> fmt::Pointer for Pin<P> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&self.pointer, f)
    }
}

// Note: 这意味着 `CoerceUnsized` 允许从 `Deref<Target=impl !Unpin>` 的类型强制转换为 `Deref<Target=Unpin>` 的类型的任何隐含声音都是不正确的。
// 但是，由于其他原因，任何这样的提示可能都不合理，因此我们只需要注意不要让这样的提示降落在 std 中。
//
//
//
#[stable(feature = "pin", since = "1.33.0")]
impl<P, U> CoerceUnsized<Pin<U>> for Pin<P> where P: CoerceUnsized<U> {}

#[stable(feature = "pin", since = "1.33.0")]
impl<P, U> DispatchFromDyn<Pin<U>> for Pin<P> where P: DispatchFromDyn<U> {}

/// 通过在本地固定 `value: T` 来构建 <code>[Pin]<[&mut] T></code>。
///
/// 与 [`Box::pin`] 不同，这不会创建新的堆分配。如下所述，该元素可能仍会在堆上结束。
///
/// 宏执行的本地固定通常称为 `栈` 固定。
/// 在 `async` 上下文之外，局部变量确实存储在栈中。然而，在 `async` 函数或块中，任何穿过 `.await` 点的局部变量都是 `Future` 捕获的状态的一部分，并将使用它们的存储。
/// 该存储可以在堆上或栈上。
/// 因此，本地固定是一个更准确的术语。
///
/// 如果给定值的类型未实现 [`Unpin`]，则此宏以防止移动的方式将值固定在内存中。
/// 另一方面，如果该类型确实实现了 [`Unpin`]，则 <code>[Pin]<[&mut] T></code> 的行为类似于 <code>[&mut] T</code>，并且 [`mem::replace()`][crate::mem::replace] 或 [`mem::take()`](crate::mem::take) 等操作将允许移动值。
///
/// 有关详细信息，请参见 [the `Unpin` section of the `pin` module][self#unpin]。
///
/// ## Examples
///
/// ### 基本用法
///
/// ```rust
/// # use core::marker::PhantomPinned as Foo;
/// use core::pin::{pin, Pin};
///
/// fn stuff(foo: Pin<&mut Foo>) {
///     // …
///     # let _ = foo;
/// }
///
/// let pinned_foo = pin!(Foo { /* … */ });
/// stuff(pinned_foo);
/// // 或者，直接:
/// stuff(pin!(Foo { /* … */ }));
/// ```
///
/// ### 手动轮询 `Future` (没有 `Unpin` 边界)
///
/// ```rust
/// use std::{
///     future::Future,
///     pin::pin,
///     task::{Context, Poll},
///     thread,
/// };
/// # use std::{sync::Arc, task::Wake, thread::Thread};
///
/// # /// 一个在调用时唤醒当前线程的唤醒器。
/// # struct ThreadWaker(Thread);
/// #
/// # impl Wake for ThreadWaker {
/// #     fn wake(self: Arc<Self>) {
/// #         self.0.unpark();
/// #     }
/// # }
/// #
/// /// 运行一个 future 直到完成。
/// fn block_on<Fut: Future>(fut: Fut) -> Fut::Output {
///     let waker_that_unparks_thread = // …
///         # Arc::new(ThreadWaker(thread::current())).into();
///     let mut cx = Context::from_waker(&waker_that_unparks_thread);
///     // 固定 future，以便可以对其进行轮询。
///     let mut pinned_fut = pin!(fut);
///     loop {
///         match pinned_fut.as_mut().poll(&mut cx) {
///             Poll::Pending => thread::park(),
///             Poll::Ready(res) => return res,
///         }
///     }
/// }
/// #
/// # assert_eq!(42, block_on(async { 42 }));
/// ```
///
/// ### 使用 `Generator`s
///
/// ```rust
/// #![feature(generators, generator_trait)]
/// use core::{
///     ops::{Generator, GeneratorState},
///     pin::pin,
/// };
///
/// fn generator_fn() -> impl Generator<Yield = usize, Return = ()> /* not Unpin */ {
///  // 允许生成器是自引用的 (不是 `Unpin`) vvvvvv 以便本地人可以跨越屈服点。
/////
///     static || {
///         let foo = String::from("foo");
///         let foo_ref = &foo; // ------+
///         yield 0;                  // | <- crosses yield point!
///         println!("{foo_ref}"); // <--+
///         yield foo.len();
///     }
/// }
///
/// fn main() {
///     let mut generator = pin!(generator_fn());
///     match generator.as_mut().resume(()) {
///         GeneratorState::Yielded(0) => {},
///         _ => unreachable!(),
///     }
///     match generator.as_mut().resume(()) {
///         GeneratorState::Yielded(3) => {},
///         _ => unreachable!(),
///     }
///     match generator.resume(()) {
///         GeneratorState::Yielded(_) => unreachable!(),
///         GeneratorState::Complete(()) => {},
///     }
/// }
/// ```
///
/// ## Remarks
///
/// 正是因为一个值被固定到本地存储，最终的 <code>[Pin]<[&mut] T></code> 引用最终借用了一个绑定到该块的本地：它无法逃脱它。
///
/// 例如，以下内容无法编译:
///
/// ```rust,compile_fail
/// use core::pin::{pin, Pin};
/// # use core::{marker::PhantomPinned as Foo, mem::drop as stuff};
///
/// let x: Pin<&mut Foo> = {
///     let x: Pin<&mut Foo> = pin!(Foo { /* … */ });
///     x
/// }; // <- Foo 已被丢弃
/// stuff(x); // 错误：使用了已经丢弃的值
/// ```
///
/// <details><summary>Error message </summary>
///
/// ```console
/// error[E0716]: temporary value dropped while borrowed
///   --> src/main.rs:9:28
///    |
/// 8  | let x: Pin<&mut Foo> = {
///    |     - borrow later stored here
/// 9  |     let x: Pin<&mut Foo> = pin!(Foo { /* … */ });
///    |                            ^^^^^^^^^^^^^^^^^^^^^ creates a temporary value which is freed while still in use
/// 10 |     x
/// 11 | }; // <- Foo 已被丢弃
///    | - temporary value is freed at the end of this statement
///    |
///    = note: consider using a `let` binding to create a longer lived value
/// ```
///
/// </details>
///
/// 这使得 [`pin!`] 在打算返回它们时不适合固定值。
/// 取而代之的是，该值预计将在 unpinned 周围传递，直到它被使用的点，然后使用 [`pin!`] 在本地固定该值是有用的，甚至是明智的。
///
/// 如果您确实需要返回固定值，请考虑改用 [`Box::pin`]。
///
/// 另一方面，使用 [`pin!`] 的本地固定可能比使用 [`Box::pin`] 固定到新的堆分配中更便宜。
/// 此外，由于不需要分配器，[`pin!`] 是主要的非 `unsafe` `#![no_std]` 兼容的 [`Pin`] 构造函数。
///
/// [`Box::pin`]: ../../std/boxed/struct.Box.html#method.pin
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "pin_macro", since = "1.68.0")]
#[rustc_macro_transparency = "semitransparent"]
#[allow_internal_unstable(unsafe_pin_internals)]
pub macro pin($value:expr $(,)?) {
    // 这是 `Pin::new_unchecked(&mut { $value })`，因此，对于初学者，让我们回顾一下这样一个假设的宏 (任何用户代码都可以定义) :
    //
    // ```rust
    // macro_rules! pin {( $value:expr ) => (
    //     match &mut { $value } { at_value => unsafe { // 不要将 `$value` 包装在 `unsafe` 块中。
    //         $crate::pin::Pin::<&mut _>::new_unchecked(at_value)
    //     }}
    // )}
    // ```
    //
    // Safety:
    //   - `type P = &mut _`.  因此，不存在会破坏 `Pin` 不，变体，的病态 `Deref{,Mut}` impl。
    //   - `{ $value }` 用大括号括起来，使其成为一个块表达式，从而移动给定的 `$value`，使其成为一个匿名 temporary。
    //     由于是匿名的，它不能再被访问，从而防止任何尝试对其进行 `mem::replace` 或 `mem::forget` 等操作。
    //
    // 这为我们提供了一个合理且有效的 `pin!` 定义，但仅适用于某些场景:
    //   - 如果将 `pin!(value)` 表达式直接提供给函数调用: `let poll = pin!(fut).poll(cx);`
    //   - 如果 `pin!(value)` 表达式是检查的一部分:
    //
    //     ```rust
    //     match pin!(fut) { pinned_fut => {
    //         pinned_fut.as_mut().poll(...);
    //         pinned_fut.as_mut().poll(...);
    //     }} // <- `fut` 在这里被丢弃了。
    //     ```
    //
    // 唉，它不适用于更直接的用例: `let` 绑定。
    //
    // ```rust
    // let pinned_fut = pin!(fut); // <- 临时值在此语句结束时被释放
    // pinned_fut.poll(...) // 错误 [E0716]: 借用时丢弃临时值
    //                      // note: 考虑使用 `let` 绑定来创建更长寿的值
    // ```
    //
    //   - 诸如此类的问题是激励 https://github.com/rust-lang/rfcs/pull/66 的原因
    //
    // 这使得这样的宏在实践中难以置信地不符合人体工程学，并且大多数宏必须采取成为 statement/binding 宏 (_e.g._，`pin!(future);`) 的路径而不是具有表达式宏的更直观的人体工程学的原因。
    //
    // 幸运的是，有一种方法可以避免这个问题。实际上，问题源于这样一个事实，即当一个临时是给函数调用的参数的一部分时，它在其封闭语句的末尾被丢弃，这正是我们的 `Pin::new_unchecked()` 的情况！
    // 例如，
    //
    // ```rust
    // let p = Pin::new_unchecked(&mut <temporary>);
    // ```
    //
    // becomes:
    //
    // ```rust
    // let p = { let mut anon = <temporary>; &mut anon };
    // ```
    //
    // 但是，当使用字面量大括号结构体构造值时，可以引用到临时对象。
    // 这使得 Rust 改变了这些临时对象的生命周期，以便它们在封装块的末尾被丢弃。
    // 例如，
    //
    // ```rust
    // let p = Pin { pointer: &mut <temporary> };
    // ```
    //
    // becomes:
    //
    // ```rust
    // let mut anon = <temporary>;
    // let p = Pin { pointer: &mut anon };
    // ```
    //
    // 这正是我们想要的。
    //
    // See https://doc.rust-lang.org/1.58.1/reference/destructors.html#temporary-lifetime-extension
    // 了解更多信息。
    $crate::pin::Pin::<&mut _> { pointer: &mut { $value } }
}