//! 键入将数据固定到其在内存中的位置的类型。
//!
//! 从对象在内存中的位置不变的意义上讲，保证对象不移动有时很有用。
//! 这种情况的一个主要示例是构建自引用结构体，因为移动带有指向自身的指针的对象会使它们无效，这可能导致未定义的行为。
//!
//! 在高层次上，<code>[Pin]\</code><P> 确保任何指针类型 `P` 的指针在内存中都有一个稳定的位置，这意味着它不能被移动到其他地方，并且它的内存不能被释放，直到它被丢弃。我们说该对象是 "pinned"。当讨论将固定数据与非固定数据结合在一起的类型时，事情变得更加微妙。[查看下文](#projections-and-structural-pinning) 了解更多详细信息。
//!
//! 默认情况下，Rust 中的所有类型都是可移动的。
//! Rust 允许按值传递所有类型，以及常见的智能指针类型，例如 <code>[Box]\</code><T> 和 <code>[&mut] T</code> 允许替换和移动它们包含的值: 您可以移出 <code>[Box]\</code><T>，或者您可以使用 [`mem::swap`]。<code>[Pin]\</code><P> 包装一个指针类型 `P`，所以 <code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></code> 函数很像一个普通的 <code>[Box]\</code><T>:
//! 当 <code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></code> 被丢弃，其内容也被丢弃，内存被释放。类似地，<code>[Pin]<[&mut] T></code>很像 <code>[&mut] T</code>。
//! 然而，<code>[Pin]\</code><P> 不让客户实际获得 <code>[Box]\</code><T> 或 <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]\</code><P> 不会改变一个事实，即 Rust 编译器认为所有类型都是可移动的。
//! [`mem::swap`] 对于任何 `T` 仍然可以调用。
//! 相反，<code>[Pin]\</code><P> 防止某些值 (由 <code>[Pin]\</code><P>) 使其无法调用需要 <code>[&mut] T</code> 方法 (如 [`mem::swap`]) 而被移动。
//!
//! <code>[Pin]\</code><P> 可用于包装任何指针类型 `P`，因此它与 [`Deref`] 和 [`DerefMut`] 交互。<code>[Pin]\</code><P>其中 <code>P: [Deref]</code> 应被视为固定 <code>P::[Target]</code>的 "`P`-style pointer" - 因此，<code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></code>是指向固定 `T` 的拥有指针，以及 <code>[Pin]<[Rc]\></code><T><code>[Pin]<[Rc]\></code> 是指向固定 `T` 的引用计数指针。
//! 为正确起见，<code>[Pin]\</code><P> 依赖于 [`Deref`] 和 [`DerefMut`] 的实现不会移出它们的 `self` 参数，并且只在固定指针上调用它们时才返回指向固定数据的指针。
//!
//! # `Unpin`
//!
//! 即使不固定，许多类型也始终可以自由移动，因为它们不依赖于具有稳定的地址。这包括所有基本类型 (如 [`bool`]，[`i32`] 和引用) 以及仅由这些类型组成的类型。不关心 pinning 的类型实现了 [`Unpin`] auto-trait，取消了 <code>[Pin]\</code><P>.
//! 对于 <code>T: [Unpin]</code>, <code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></code> 和 <code>[Box]\</code><T> 函数相同，<code>[Pin]<[&mut] T></code> 和 <code>[&mut] T</code>。
//!
//! 请注意，固定和 [`Unpin`] 仅影响指向类型 <code>P::[Target]</code>，而不影响包含在 <code>[Pin]\</code> 的指针类型 `P` 本身 <P>.
//! 例如，是否 <code>[Box]\</code><T> 是 [`Unpin`] 对 <code>[Pin]<[Box]\></code> 的行为没有影响 <T><code>[Pin]<[Box]\></code> (这里，`T` 是指向类型)。
//!
//! # 示例: 自我参照结构体
//!
//! 在我们详细解释与 <code>[Pin]\</code> 相关的保证和选择之前 <code>[Pin]\</code><P>，我们讨论了一些如何使用它的例子。
//! 随时使用 [skip to where the theoretical discussion continues](#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` guarantee
//!
//! 固定的目的是能够依靠某些数据在内存中的放置。
//! 为了使这项工作有效，不仅限制了移动数据，还限制了数据的传输。限制用于存储数据的内存的重新分配，重新分配用途或以其他方式使之无效。
//! 具体来说，对于固定的数据，必须保持不变，即从固定 *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]\></code><T><code>[Pin]<[Box]\></code>)。在双向链表的示例中，该元素将仅保留在列表中。但是，您可能无法释放或重新使用存储 *without calling [`drop`]*。
//!
//! # `Drop` implementation
//!
//! 如果您的类型使用固定 (例如上面的两个示例)，则在实现 [`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>?</code>
//! `enum` 的字段以及在考虑 container/wrapper 类型 (例如 <code>[Vec]\</code><T>, <code>[Box]\</code><T>, 或 <code>[RefCell]\</code><T>.
//! (此问题适用于可变引用和共享引用，我们仅在此处使用可变引用的更常见情况进行说明。)
//!
//! 事实证明，实际上是由数据结构的作者决定特定字段的固定 projection 是将 <code>[Pin]<[&mut] 结构体 ></code> 转换为 <code>[Pin]<[&mut] Field></code> 或 <code>[&mut] Field</code>.</code> 但是有一些约束，最重要的约束是 *consistency*:
//! 每个字段都可以 *或者* 投影到固定的引用，或者 * 可以删除固定作为投影的一部分。
//! 如果两者都在同一个领域完成，那将是不正确的!
//!
//! 作为数据结构体的作者，您可以为每个字段决定是否将 "propagates" 固定到该字段。
//! 传播的固定也称为 "structural"，因为它遵循该类型的结构体。
//! 在以下各小节中，我们描述了两种选择都必须考虑的因素。
//!
//! ## Pinning 不是用于结构体的 `field`
//!
//! 固定结构体的字段可能不被固定似乎违反直觉，但这实际上是最简单的选择: 如果从未创建 <code>[Pin]<[&mut] Field></code> 则不会出错! 因此，如果您确定某个字段不具有结构固定，则只需确保您从未创建对该字段的固定引用即可。
//!
//! 没有结构固定的字段可能具有将 <code>[Pin]<[&mut] 结构体 ></code> 转换为 <code>[&mut] Field</code>:</code> 的 projection 方法 <code>[&mut] Field</code>:</code>
//!
//! ```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> 当没有创建 <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 结构体 \</code><T> <code>impl\[Unpin] for 结构体 \</code><T>. (请注意，添加投影操作需要不安全的代码，因此 [`Unpin`] 是安全的 trait 的事实并没有破坏您只需要在使用 [`unsafe`] 时担心任何这些的原则。)
//! 2. 结构体的析构函数不得将结构域移出其参数。这正是 [上一节][drop-impl] 中提出的要点: [`drop`] 采用 <code>[&mut] self</code>，但是结构体 (以及它的字段) 之前可能已经被固定了。</code> 您必须保证不会在您的 [`Drop`][Drop] 实现中移动任何字段。特别是，如前所述，这意味着您的结构体 *不能* 为 `#[repr(packed)]`。
//!     有关如何编写 [`drop`] 的方法，请参见该部分，以使编译器可以帮助您避免意外破坏固定。
//! 3. 您必须确保坚持使用 [`Drop` 保证][drop-guarantee]:
//!     一旦固定了您的结构体，包含内容的内存就不会被覆盖或释放，而无需调用内容的析构函数。
//!     这可能很棘手，正如 <code>[VecDeque]\</code><T>: <code>[VecDeque]\</code> 的析构函数 <code>[VecDeque]\</code><T> 如果析构函数 panics 之一，则可能无法在所有元素上调用 [`drop`]。这违反了 [`Drop`][Drop] 保证，因为它可能导致元素在没有调用析构函数的情况下被释放。
//!     (<code>[VecDeque]\</code><T> 没有固定 projection，所以这不会导致不稳定。)
//! 4. 固定类型时，不得提供可能导致数据移出结构字段的任何其他操作。例如，如果结构体包含一个 <code>[Option]\</code><T>并且有一个类似 [`take`][Option::take] 的操作，类型为 <code>fn ([Pin]<[&mut] 结构体 \>) -> [Option]\</code><T> <code>fn ([Pin]<[&mut] 结构体 \>) -> [Option]\</code><T>，该操作可用于将 `T` 从固定的 `Struct<T>` 中移出 - 这意味着固定不能对保存此数据的字段进行结构化。
//!
//!     有关将数据移出固定类型的更复杂示例，请想象如果 <code>[RefCell]\</code><T>有一个方法 <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]\</code><T> (使用 <code>[RefCell]::get_pin_mut</code> ) 然后使用我们稍后获得的 <code>[RefCell]::get_pin_mut</code> 引用移动该内容。
//!
//! ## Examples
//!
//! 对于像 <code>[Vec]\</code> 这样的类型 <T>，两种可能性 (结构固定与否) 都有意义。<code>[Vec]\</code><T> 使用结构固定可以有 `get_pin`/`get_pin_mut` 方法来固定引用到元素。但是，它可能*不允许*在固定的 <code>[Vec]\</code> 上调用 [`pop`][Vec::pop]<T> 因为那会移动 (结构固定的) 内容! 它也不允许 [`push`][Vec::push]，它可能会重新分配并因此也移动内容。
//!
//! <code>[Vec]\</code><T>没有结构固定可以 <code>impl\[Unpin] for [Vec]\</code><T> <code>impl\[Unpin] for [Vec]\</code><T>，因为内容永远不会被固定并且 <code>[Vec]\</code><T> 本身也可以移动。
//! 那时，固定对 vector 完全没有影响。
//!
//! 在标准库中，指针类型通常不具有结构固定，因此它们不提供固定投影。这就是为什么 <code>[Box]\: [Unpin]</code><T><code>[Box]\: [Unpin]</code> Unpin <code>[Box]\: [Unpin]</code> 适用于所有 `T`。对指针类型这样做是有意义的，因为移动 <code>[Box]\</code><T> 实际上并没有移动 `T`: <code>[Box]\</code><T> 即使 `T` 不是，也可以自由移动 (又名 [`Unpin`])。
//! 事实上，即使 <code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></code> 和 <code>[Pin]<[&mut] T></code> 总是 [`Unpin`] 本身，原因相同:
//! 它们的内容 (`T`) 是固定的，但指针本身可以在不移动固定数据的情况下移动。
//! 对于 <code>[Box]\</code><T> 和 <code>[Pin]<[Box]\></code><T><code>[Pin]<[Box]\></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 "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"
//! [&]: ../../std/primitive.reference.html "shared reference"
//! [&mut]: ../../std/primitive.reference.html "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` 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> {
    pointer: P,
}

// 为了避免出现健全性问题，没有实现以下实现。
// `&self.pointer` 不受信任的 trait 实现不应访问。
//
// 有关更多详细信息，请参见 <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`] 类型，从而取消了固定保证。
    ///
    ///
    #[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`]，以便我们在展开包装时可以忽略固定不变式。
    ///
    #[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);
    ///     // `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();
    ///     // 现在，如果 `x` 是唯一的引用，则对上面固定的数据有一个变量引用，就像在上一个示例中看到的那样，我们可以使用它来移动它。
    ///     // 我们违反了固定 API 契约。
    /////
    ///  }
    ///  ```
    ///
    /// [`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>>` 之后，指针无法移动。
    ///
    /// "Malicious" `Pointer::Deref` 的实现同样被 `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>>` 之后，指针无法移动。
    ///
    /// "Malicious" `Pointer::DerefMut` 的实现同样被 `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) }
    }

    /// 为固定的引用后面的内存分配一个新值。
    ///
    /// 这会覆盖固定的数据，但是没关系: 它的析构函数在被覆盖之前就已运行，因此不会违反固定保证。
    ///
    #[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) }
    }

    /// 从大头针获取共享的引用。
    ///
    /// 这是安全的，因为不可能移出共享引用。
    /// 内部可变性似乎存在问题: 实际上，可以将 `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)]
    #[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)]
    #[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)]
    #[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)]
    #[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
    ///
    ///
    #[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` 生命周期的借用，而生命周期永远不会结束。
    ///
    #[unstable(feature = "pin_static_ref", issue = "78186")]
    #[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<T: ?Sized> Pin<&'static mut T> {
    /// 从静态变量引用中获取固定的变量引用。
    ///
    /// 这是安全的，因为 `T` 是 `'static` 生命周期的借用，而生命周期永远不会结束。
    ///
    #[unstable(feature = "pin_static_ref", issue = "78186")]
    #[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> {}