//! 原始 traits 和类型表示类型的基本属性。
//!
//! Rust 类型可以根据其固有属性以各种有用的方式进行分类。
//! 这些分类表示为 traits。
//!

#![stable(feature = "rust1", since = "1.0.0")]

use crate::cell::UnsafeCell;
use crate::cmp;
use crate::fmt::Debug;
use crate::hash::Hash;
use crate::hash::Hasher;

/// 可以跨线程边界传输的类型。
///
/// 当编译器确定适当时，会自动实现此 trait。
///
/// 非 `Send` 类型的一个示例是引用计数指针 [`rc::Rc`][`Rc`]。
/// 如果两个线程试图克隆指向相同引用计数值的 [`Rc`]，它们可能会同时尝试更新引用计数，这是 [未定义行为][ub] 因为 [`Rc`] 不使用原子操作。
///
/// 它的表亲 [`sync::Arc`][arc] 确实使用原子操作 (产生一些开销)，因此它是 `Send`。
///
/// 有关更多详细信息，请参见 [the Nomicon](../../nomicon/send-and-sync.html)。
///
/// [`Rc`]: ../../std/rc/struct.Rc.html
/// [arc]: ../../std/sync/struct.Arc.html
/// [ub]: ../../reference/behavior-considered-undefined.html
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "send_trait")]
#[rustc_on_unimplemented(
    message = "`{Self}` cannot be sent between threads safely",
    label = "`{Self}` cannot be sent between threads safely"
)]
pub unsafe auto trait Send {
    // empty.
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> !Send for *const T {}
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> !Send for *mut T {}

/// 在编译时已知常量大小的类型。
///
/// 所有类型参数的隐含边界均为 `Sized`。如果不合适，可以使用特殊语法 `?Sized` 删除此绑定。
///
/// ```
/// # #![allow(dead_code)]
/// struct Foo<T>(T);
/// struct Bar<T: ?Sized>(T);
///
/// // struct FooUse(Foo<[i32]>); // 错误: 没有为 [i32] 实现大小调整
/// struct BarUse(Bar<[i32]>); // OK
/// ```
///
/// 一个例外是 trait 的隐式 `Self` 类型。
/// trait 没有隐式 `Sized` 绑定，因为它与 [trait 对象][trait object] 不兼容，根据定义，trait 需要与所有可能的实现者一起使用，因此可以为任意大小。
///
///
/// 尽管 Rust 允许您将 `Sized` 绑定到 trait，但是以后您将无法使用它来形成 trait 对象:
///
/// ```
/// # #![allow(unused_variables)]
/// trait Foo { }
/// trait Bar: Sized { }
///
/// struct Impl;
/// impl Foo for Impl { }
/// impl Bar for Impl { }
///
/// let x: &dyn Foo = &Impl;    // OK
/// // let y: &dyn Bar = &Impl; // 错误: 无法将 trait `Bar` 创建成对象
/////
/// ```
///
/// [trait object]: ../../book/ch17-02-trait-objects.html
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[lang = "sized"]
#[rustc_on_unimplemented(
    message = "the size for values of type `{Self}` cannot be known at compilation time",
    label = "doesn't have a size known at compile-time"
)]
#[fundamental] // 例如，对于 Default，它要求 `[T]: !Default` 必须是可评估的
#[rustc_specialization_trait]
pub trait Sized {
    // Empty.
}

/// 可以是未定义大小的类型也可以是动态大小的类型。
///
/// 例如，按大小排列的数组类型 `[i8; 2]` 实现 `Unsize<[i8]>` 和 `Unsize<dyn fmt::Debug>`。
///
/// `Unsize` 的所有实现均由编译器自动提供。
///
/// `Unsize` 为以下目的实现:
///
/// - `[T; N]` 是 `Unsize<[T]>`
/// - `T` `T: Trait` 时为 `Unsize<dyn Trait>`
/// - `Foo<..., T, ...>` 如果是，则为 `Unsize<Foo<..., U, ...>>`:
///   - `T: Unsize<U>`
///   - Foo 是一个结构体
///   - 仅 `Foo` 的最后一个字段具有涉及 `T` 的类型
///   - `T` 不属于任何其他字段的类型
///   - `Bar<T>: Unsize<Bar<U>>`, 如果 `Foo` 的最后一个字段的类型为 `Bar<T>`
///
/// `Unsize` 与 [`ops::CoerceUnsized`] 一起使用可允许 "user-defined" 容器 (例如 [`Rc`]) 包含动态大小的类型。
/// 有关更多详细信息，请参见 [DST coercion RFC][RFC982] 和 [the nomicon entry on coercion][nomicon-coerce]。
///
/// [`ops::CoerceUnsized`]: crate::ops::CoerceUnsized
/// [`Rc`]: ../../std/rc/struct.Rc.html
/// [RFC982]: https://github.com/rust-lang/rfcs/blob/master/text/0982-dst-coercion.md
/// [nomicon-coerce]: ../../nomicon/coercions.html
///
///
///
#[unstable(feature = "unsize", issue = "27732")]
#[lang = "unsize"]
pub trait Unsize<T: ?Sized> {
    // Empty.
}

/// 模式匹配中使用的常量需要 trait。
///
/// 不管其类型参数是否实现 `Eq`，任何派生 `PartialEq` 的类型都会自动实现此 trait。
///
/// 如果 `const` 项包含某种不实现此 trait 的类型，则该类型要么 (1.) 不实现 `PartialEq` (这意味着常量将不提供该比较方法 (代码生成假定可用) )，要么 (2.) 自身实现 *its*`PartialEq` 的版本 (我们认为不符合结构相等性比较)。
///
///
/// 在以上两种情况中的任何一种情况下，我们都拒绝在模式匹配中使用此类常量。
///
/// 另请参见 [structural match RFC][RFC1445] 和 [issue 63438]，它们促使从基于属性的设计迁移到此 trait。
///
/// [RFC1445]: https://github.com/rust-lang/rfcs/blob/master/text/1445-restrict-constants-in-patterns.md
/// [issue 63438]: https://github.com/rust-lang/rust/issues/63438
///
///
///
///
///
///
///
#[unstable(feature = "structural_match", issue = "31434")]
#[rustc_on_unimplemented(message = "the type `{Self}` does not `#[derive(PartialEq)]`")]
#[lang = "structural_peq"]
pub trait StructuralPartialEq {
    // Empty.
}

/// 模式匹配中使用的常量需要 trait。
///
/// 派生 `Eq` 的任何类型都会自动实现此 trait，无论其类型参数是否实现 `Eq`。
///
/// 这是一种解决我们类型系统限制的技巧。
///
/// # Background
///
/// 我们要要求模式匹配中使用的 const 类型具有属性 `#[derive(PartialEq, Eq)]`。
///
/// 在更理想的世界中，我们可以通过仅检查给定类型是否同时实现 `StructuralPartialEq` trait 和 `Eq` trait 来检查该要求。
/// 但是，您可能拥有 *do*`derive(PartialEq, Eq)` 的 ADT，这是我们希望编译器接受的情况，但是 const 的类型无法实现 `Eq`。
///
/// 即，这样的情况:
///
/// ```rust
/// #[derive(PartialEq, Eq)]
/// struct Wrap<X>(X);
///
/// fn higher_order(_: &()) { }
///
/// const CFN: Wrap<fn(&())> = Wrap(higher_order);
///
/// fn main() {
///     match CFN {
///         CFN => {}
///         _ => {}
///     }
/// }
/// ```
///
/// (以上代码中的问题是 `Wrap<fn(&())>` 既不实现 `PartialEq` 也不实现 `Eq`，因为 `for <'a> fn(&'a _)` does not implement those traits.)
///
/// 因此，我们不能仅仅依靠 `StructuralPartialEq` 和 `Eq` 的幼稚检查。
///
/// 要解决此问题，我们使用两个派生对象 (`#[derive(PartialEq)]` 和 `#[derive(Eq)]`) 中的每个派生注入的两个单独的 traits，并检查它们是否都作为结构匹配检查的一部分出现。
///
///
///
///
///
///
///
///
///
///
#[unstable(feature = "structural_match", issue = "31434")]
#[rustc_on_unimplemented(message = "the type `{Self}` does not `#[derive(Eq)]`")]
#[lang = "structural_teq"]
pub trait StructuralEq {
    // Empty.
}

/// 只需复制位即可复制其值的类型。
///
/// 默认情况下，变量绑定具有移动语义。换句话说:
///
/// ```
/// #[derive(Debug)]
/// struct Foo;
///
/// let x = Foo;
///
/// let y = x;
///
/// // `x` 已移至 `y`，因此无法使用
///
/// // println!("{:?}", x); // error: use of moved value
/// ```
///
/// 但是，如果类型实现 `Copy`，则它具有复制语义:
///
/// ```
/// // 我们可以派生一个 `Copy` 实现。
/// // `Clone` 也是必需的，因为它是 `Copy` 的特征。
/// #[derive(Debug, Copy, Clone)]
/// struct Foo;
///
/// let x = Foo;
///
/// let y = x;
///
/// // `y` 是 `x` 的副本
///
/// println!("{:?}", x); // A-OK!
/// ```
///
/// 重要的是要注意，在这两个示例中，唯一的区别是分配后是否允许您访问 `x`。
/// 在后台，复制和移动都可能导致将位复制到内存中，尽管有时会对其进行优化。
///
/// ## 如何实现 `Copy`?
///
/// 有两种方法可以在您的类型上实现 `Copy`。最简单的是使用 `derive`:
///
/// ```
/// #[derive(Copy, Clone)]
/// struct MyStruct;
/// ```
///
/// 您还可以手动实现 `Copy` 和 `Clone`:
///
/// ```
/// struct MyStruct;
///
/// impl Copy for MyStruct { }
///
/// impl Clone for MyStruct {
///     fn clone(&self) -> MyStruct {
///         *self
///     }
/// }
/// ```
///
/// 两者之间的区别很小: `derive` 策略还将 `Copy` 绑定在类型参数上，这并不总是需要的。
///
/// ## `Copy` 和 `Clone` 有什么区别?
///
/// 复制是隐式发生的，例如作为工作 `y = x` 的一部分。`Copy` 的行为不可重载; 它始终是简单的按位复制。
///
/// 克隆是一个明确的动作 `x.clone()`。[`Clone`] 的实现可以提供安全复制值所需的任何特定于类型的行为。
/// 例如，用于 [`String`] 的 [`Clone`] 的实现需要在堆中复制指向字符串的缓冲区。
/// [`String`] 值的简单按位副本将仅复制指针，从而导致该行向下双重释放。
/// 因此，[`String`] 是 [`Clone`]，但不是 `Copy`。
///
/// [`Clone`] 是 `Copy` 的特征，因此 `Copy` 的所有内容也必须实现 [`Clone`]。
/// 如果类型为 `Copy`，则其 [`Clone`] 实现仅需要返回 `*self` (请参见上面的示例)。
///
/// ## 什么时候可以输入 `Copy`?
///
/// 如果类型的所有组件都实现 `Copy`，则它可以实现 `Copy`。例如，此结构体可以是 `Copy`:
///
/// ```
/// # #[allow(dead_code)]
/// #[derive(Copy, Clone)]
/// struct Point {
///    x: i32,
///    y: i32,
/// }
/// ```
///
/// 一个结构体可以是 `Copy`，而 [`i32`] 是 `Copy`，因此 `Point` 有资格成为 `Copy`。
/// 相比之下，考虑
///
/// ```
/// # #![allow(dead_code)]
/// # struct Point;
/// struct PointList {
///     points: Vec<Point>,
/// }
/// ```
///
/// 结构体 `PointList` 无法实现 `Copy`，因为 [`Vec<T>`] 不是 `Copy`。如果尝试派生 `Copy` 实现，则会收到错误消息:
///
/// ```text
/// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy`
/// ```
///
/// 共享引用 (`&T`) 也是 `Copy`，因此，即使类型中包含 *04* 不是*`Copy` 类型的共享引用 `T`，也可以是 `Copy`。
/// 考虑下面的结构体，它可以实现 `Copy`，因为它从上方仅对我们的非 Copy 类型 `PointList` 持有一个 *shared 引用*:
///
/// ```
/// # #![allow(dead_code)]
/// # struct PointList;
/// #[derive(Copy, Clone)]
/// struct PointListWrapper<'a> {
///     point_list_ref: &'a PointList,
/// }
/// ```
///
/// ## 什么时候我的类型不能为 `Copy`?
///
/// 某些类型无法安全复制。例如，复制 `&mut T` 将创建一个别名可变引用。
/// 复制 [`String`] 将重复管理 [`String`] 缓冲区，从而导致双重释放。
///
/// 概括后一种情况，任何实现 [`Drop`] 的类型都不能是 `Copy`，因为它除了管理自己的 [`size_of::<T>`] 字节外还管理一些资源。
///
/// 果您尝试在包含非 `Copy` 数据的结构或枚举上实现 `Copy`，则会收到 [E0204] 错误。
///
/// [E0204]: ../../error-index.html#E0204
///
/// ## 什么时候我的类型应该是 `Copy`?
///
/// 一般来说，如果您的类型可以实现 `Copy`，则应该这样做。
/// 但是请记住，实现 `Copy` 是您类型的公共 API 的一部分。
/// 如果该类型将来可能变为非 `Copy`，则最好现在省略 `Copy` 实现，以避免 API 发生重大更改。
///
/// ## 其他实现者
///
/// 除 [下面列出的实现者][impls] 之外，以下类型还实现 `Copy`:
///
/// * 函数项类型 (即，为每个函数定义的不同类型)
/// * 函数指针类型 (例如 `fn() -> i32`)
/// * 如果项类型也实现 `Copy` (例如 `[i32; 123456]`)，则所有大小的数组类型
/// * 如果每个组件还实现 `Copy` (例如 `()`，`(i32, bool)`)，则为元组类型
/// * 闭包类型，如果它们没有从环境中捕获任何值，或者所有此类捕获的值本身都实现了 `Copy`。
///   请注意，由共享引用捕获的变量始终实现 `Copy` (即使引用对象没有实现)，而由变量引用捕获的变量从不实现 `Copy`。
///
///
/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
/// [`String`]: ../../std/string/struct.String.html
/// [`size_of::<T>`]: crate::mem::size_of
/// [impls]: #implementors
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[lang = "copy"]
// FIXME(matthewjasper) 这允许复制由于生命周期界限不令人满意而无法实现 `Copy` 的类型 (仅 `A<'static>: Copy` 和 `A<'_>: Clone` 时复制 `A<'_>`)。
// 我们现在在这里具有此属性的原因仅是因为标准库中已经存在 `Copy` 上的许多现有专长，并且目前尚无办法安全地具有此行为。
//
//
//
//
#[rustc_unsafe_specialization_marker]
pub trait Copy: Clone {
    // Empty.
}

/// 派生宏，生成 `Copy` trait 的 impl。
#[rustc_builtin_macro]
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow_internal_unstable(core_intrinsics, derive_clone_copy)]
pub macro Copy($item:item) {
    /* compiler built-in */
}

/// 可以在线程之间安全共享引用的类型。
///
/// 当编译器确定适当时，会自动实现此 trait。
///
/// 精确的定义是: 当且仅当 `&T` 是 [`Send`] 时，类型 `T` 才是 [`Sync`]。
/// 换句话说，如果在线程之间传递 `&T` 引用时没有 [未定义的行为][ub] (包括数据竞争) 的可能性。
///
/// 正如人们所期望的那样，原始类型 (如 [`u8`] 和 [`f64`]) 都是 [`Sync`]，包含它们的简单聚合类型 (如元组，结构体和枚举) 也是如此。
/// 基本 [`Sync`] 类型的更多示例包括不可变类型 (例如 `&T`) 以及具有简单继承的可变性的类型，例如 [`Box<T>`][box]，[`Vec<T>`][vec] 和大多数其他集合类型。
///
/// (泛型参数必须为 [`Sync`]，容器才能 [[Sync]]。)
///
/// 该定义的一个令人惊讶的结果是 `&mut T` 是 `Sync` (如果 `T` 是 `Sync`)，即使看起来可能提供了不同步的可变的。
/// 诀窍是，共享引用 (即 `& &mut T`) 后面的可变引用将变为只读，就好像它是 `& &T` 一样。
/// 因此，没有数据竞争的风险。
///
/// 不是 `Sync` 的类型是具有非线程安全形式的 "interior mutability" 的类型，例如 [`Cell`][cell] 和 [`RefCell`][refcell]。
/// 这些类型甚至允许通过不可变，共享引用来更改其内容。
/// 例如，[`Cell<T>`][cell] 上的 `set` 方法采用 `&self`，因此它仅需要共享的引用 [`&Cell<T>`][cell]。
/// 该方法不执行同步，因此 [`Cell`][cell] 不能为 `Sync`。
///
/// 另一个非 `Sync` 类型的例子是引用计数指针 [`Rc`][rc]。
/// 给定任何引用 [`&Rc<T>`][rc]，您可以克隆新的 [`Rc<T>`][rc]，以非原子方式修改引用计数。
///
/// 对于确实需要线程安全的内部可变性的情况，Rust 提供 [atomic data types] 以及通过 [`sync::Mutex`][mutex] 和 [`sync::RwLock`][rwlock] 进行的显式锁定。
/// 这些类型可确保任何可变的都不会引起数据竞争，因此类型为 `Sync`。
/// 同样，[`sync::Arc`][arc] 提供了 [`Rc`][rc] 的线程安全模拟。
///
/// 任何具有内部可变性的类型还必须在 value(s) 周围使用 [`cell::UnsafeCell`][unsafecell] 包装器，该包装器可以通过共享的引用进行更改。
/// [未定义的行为][ub] 无法做到这一点。
/// 例如，从 `&T` 到 `&mut T` 的 [`transmute`][transmute] 无效。
///
/// 有关 `Sync` 的更多详细信息，请参见 [the Nomicon][nomicon-send-and-sync]。
///
/// [box]: ../../std/boxed/struct.Box.html
/// [vec]: ../../std/vec/struct.Vec.html
/// [cell]: crate::cell::Cell
/// [refcell]: crate::cell::RefCell
/// [rc]: ../../std/rc/struct.Rc.html
/// [arc]: ../../std/sync/struct.Arc.html
/// [atomic data types]: crate::sync::atomic
/// [mutex]: ../../std/sync/struct.Mutex.html
/// [rwlock]: ../../std/sync/struct.RwLock.html
/// [unsafecell]: crate::cell::UnsafeCell
/// [ub]: ../../reference/behavior-considered-undefined.html
/// [transmute]: crate::mem::transmute
/// [nomicon-send-and-sync]: ../../nomicon/send-and-sync.html
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "sync_trait")]
#[lang = "sync"]
#[rustc_on_unimplemented(
    message = "`{Self}` cannot be shared between threads safely",
    label = "`{Self}` cannot be shared between threads safely"
)]
pub unsafe auto trait Sync {
    // FIXME(estebank): 一旦在 `rustc_on_unimplemented` 中添加 note 的支持进入 beta 版本，并且已经扩展到检查闭包是否在需求链中的任何地方，就这样扩展它 (#48534):
    //
    //
    // ```
    // on(
    //     closure,
    //     note="`{Self}` cannot be shared safely, consider marking the closure `move`"
    // ),
    // ```

    // Empty
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> !Sync for *const T {}
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> !Sync for *mut T {}

macro_rules! impls {
    ($t: ident) => {
        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> Hash for $t<T> {
            #[inline]
            fn hash<H: Hasher>(&self, _: &mut H) {}
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> cmp::PartialEq for $t<T> {
            fn eq(&self, _other: &$t<T>) -> bool {
                true
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> cmp::Eq for $t<T> {}

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> cmp::PartialOrd for $t<T> {
            fn partial_cmp(&self, _other: &$t<T>) -> Option<cmp::Ordering> {
                Option::Some(cmp::Ordering::Equal)
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> cmp::Ord for $t<T> {
            fn cmp(&self, _other: &$t<T>) -> cmp::Ordering {
                cmp::Ordering::Equal
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> Copy for $t<T> {}

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> Clone for $t<T> {
            fn clone(&self) -> Self {
                Self
            }
        }

        #[stable(feature = "rust1", since = "1.0.0")]
        impl<T: ?Sized> Default for $t<T> {
            fn default() -> Self {
                Self
            }
        }

        #[unstable(feature = "structural_match", issue = "31434")]
        impl<T: ?Sized> StructuralPartialEq for $t<T> {}

        #[unstable(feature = "structural_match", issue = "31434")]
        impl<T: ?Sized> StructuralEq for $t<T> {}
    };
}

/// 零大小的类型用来标记那些行为像它们拥有一个 `T` 的东西。
///
/// 向您的类型添加 `PhantomData<T>` 字段将告诉编译器，您的类型的行为就像它存储了 `T` 类型的值一样，即使实际上并非如此。
/// 在计算某些安全属性时会使用此信息。
///
/// 有关如何使用 `PhantomData<T>` 的更深入的说明，请参见 [the Nomicon](../../nomicon/phantom-data.html)。
///
/// # 一个可怕的笔记 👻👻👻
///
/// 尽管它们都有可怕的名称，但 `PhantomData` 和 phantom 类型是相关的，但并不完全相同。phantom 类型参数只是从未使用过的类型参数。
/// 在 Rust 中，这通常会导致编译器抱怨，而解决方案是通过 `PhantomData` 添加 "dummy" 用途。
///
/// # Examples
///
/// ## 未使用的生命周期参数
///
/// `PhantomData` 的最常见用例也许是具有未使用的生命周期参数的结构体，通常将其用作某些不安全代码的一部分。
/// 例如，这是一个结构体 `Slice`，它具有两个 `*const T` 类型的指针，大概指向某个地方的数组:
///
/// ```compile_fail,E0392
/// struct Slice<'a, T> {
///     start: *const T,
///     end: *const T,
/// }
/// ```
///
/// 目的是基础数据仅对生命周期 `'a` 有效，因此 `Slice` 不应超过 `'a`。
/// 但是，此意图未在代码中表达，因为没有使用生命周期 `'a`，因此尚不清楚它适用于什么数据。
/// 我们可以通过告诉编译器如果 `Slice` 结构体包含引用 `&'a T` 来执行 *as 来纠正此问题:
///
/// ```
/// use std::marker::PhantomData;
///
/// # #[allow(dead_code)]
/// struct Slice<'a, T: 'a> {
///     start: *const T,
///     end: *const T,
///     phantom: PhantomData<&'a T>,
/// }
/// ```
///
/// 这也需要注解 `T: 'a`，以指示 `T` 中的所有引用在生命周期 `'a` 上均有效。
///
/// 初始化 `Slice` 时，只需为字段 `phantom` 提供值 `PhantomData`:
///
/// ```
/// # #![allow(dead_code)]
/// # use std::marker::PhantomData;
/// # struct Slice<'a, T: 'a> {
/// #     start: *const T,
/// #     end: *const T,
/// #     phantom: PhantomData<&'a T>,
/// # }
/// fn borrow_vec<T>(vec: &Vec<T>) -> Slice<'_, T> {
///     let ptr = vec.as_ptr();
///     Slice {
///         start: ptr,
///         end: unsafe { ptr.add(vec.len()) },
///         phantom: PhantomData,
///     }
/// }
/// ```
///
/// ## 未使用的类型参数
///
/// 有时可能会发生未使用的类型参数，这些参数指示 "tied" 将结构体数据类型化的数据，即使该数据实际上不是在结构体本身中找到的也是如此。
/// 这是 [FFI] 出现此情况的示例。
/// 外部接口使用 `*mut ()` 类型的句柄来引用不同类型的 Rust 值。
/// 我们使用包裹句柄的结构体 `ExternalResource` 上的 `phantom` 类型参数来跟踪 Rust 类型。
///
/// [FFI]: ../../book/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code
///
/// ```
/// # #![allow(dead_code)]
/// # trait ResType { }
/// # struct ParamType;
/// # mod foreign_lib {
/// #     pub fn new(_: usize) -> *mut () { 42 as *mut () }
/// #     pub fn do_stuff(_: *mut (), _: usize) {}
/// # }
/// # fn convert_params(_: ParamType) -> usize { 42 }
/// use std::marker::PhantomData;
/// use std::mem;
///
/// struct ExternalResource<R> {
///    resource_handle: *mut (),
///    resource_type: PhantomData<R>,
/// }
///
/// impl<R: ResType> ExternalResource<R> {
///     fn new() -> Self {
///         let size_of_res = mem::size_of::<R>();
///         Self {
///             resource_handle: foreign_lib::new(size_of_res),
///             resource_type: PhantomData,
///         }
///     }
///
///     fn do_stuff(&self, param: ParamType) {
///         let foreign_params = convert_params(param);
///         foreign_lib::do_stuff(self.resource_handle, foreign_params);
///     }
/// }
/// ```
///
/// ## 所有权和 drop 检测
///
/// 添加 `PhantomData<T>` 类型的字段表示您的类型拥有 `T` 类型的数据。反过来，这意味着丢弃您的类型时，它可能会丢弃一个或多个 `T` 类型的实例。
/// 这与 Rust 编译器的 [drop check] 分析有关。
///
/// 如果您的结构体实际上并不 *拥有*`T` 类型的数据，则最好使用引用类型，例如 `PhantomData<&'a T>` (ideally) 或 `PhantomData<*const T>` (如果没有生命周期适用)，以免表示所有权。
///
///
/// [drop check]: ../../nomicon/dropck.html
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[lang = "phantom_data"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct PhantomData<T: ?Sized>;

impls! { PhantomData }

mod impls {
    #[stable(feature = "rust1", since = "1.0.0")]
    unsafe impl<T: Sync + ?Sized> Send for &T {}
    #[stable(feature = "rust1", since = "1.0.0")]
    unsafe impl<T: Send + ?Sized> Send for &mut T {}
}

/// 编译器内部的 trait 用于指示枚举判别式的类型。
///
/// trait 会自动为每种类型实现，并且不会为 [`mem::Discriminant`] 添加任何保证。
/// 在 `DiscriminantKind::Discriminant` 和 `mem::Discriminant` 之间转换是未定义的行为。
///
/// [`mem::Discriminant`]: crate::mem::Discriminant
///
#[unstable(
    feature = "discriminant_kind",
    issue = "none",
    reason = "this trait is unlikely to ever be stabilized, use `mem::discriminant` instead"
)]
#[lang = "discriminant_kind"]
pub trait DiscriminantKind {
    /// 判别类型，必须满足 `mem::Discriminant` 要求的 trait bounds。
    ///
    #[lang = "discriminant_type"]
    type Discriminant: Clone + Copy + Debug + Eq + PartialEq + Hash + Send + Sync + Unpin;
}

/// 编译器内部的 trait 用于确定类型是否在内部包含任何 `UnsafeCell`，但不是通过间接寻址。
///
/// 例如，这会影响该类型的 `static` 是否放置在只读静态存储器或可写静态存储器中。
///
#[lang = "freeze"]
pub(crate) unsafe auto trait Freeze {}

impl<T: ?Sized> !Freeze for UnsafeCell<T> {}
unsafe impl<T: ?Sized> Freeze for PhantomData<T> {}
unsafe impl<T: ?Sized> Freeze for *const T {}
unsafe impl<T: ?Sized> Freeze for *mut T {}
unsafe impl<T: ?Sized> Freeze for &T {}
unsafe impl<T: ?Sized> Freeze for &mut T {}

/// 固定后可以安全移动的类型。
///
/// Rust 本身没有固定类型的概念，并认为移动 (例如，通过赋值或 [`mem::replace`]) 始终是安全的。
///
/// [`Pin`][Pin] 类型代替使用，以防止在类型系统中移动。[`Pin<P<T>>`][Pin] 包装器中包裹的指针 `P<T>` 不能移出。
/// 有关固定的更多信息，请参见 [`pin` module] 文档。
///
/// 为 `T` 实现 `Unpin` trait 消除了固定该类型的限制，然后允许使用诸如 [`mem::replace`] 之类的功能将 `T` 从 [`Pin<P<T>>`][Pin] 中移出。
///
///
/// `Unpin` 对于非固定数据完全没有影响。
/// 特别是，[`mem::replace`] 可以愉快地移动 `!Unpin` 数据 (它适用于任何 `&mut T`，而不仅限于 `T: Unpin`)。
/// 但是，您不能对包装在 [`Pin<P<T>>`][Pin] 内的数据使用 [`mem::replace`]，因为您无法获得所需的 `&mut T`，并且 *that* 是使此系统正常工作的原因。
///
/// 因此，例如，这只能在实现 `Unpin` 的类型上完成:
///
/// ```rust
/// # #![allow(unused_must_use)]
/// use std::mem;
/// use std::pin::Pin;
///
/// let mut string = "this".to_string();
/// let mut pinned_string = Pin::new(&mut string);
///
/// // 我们需要一个可变引用来调用 `mem::replace`。
/// // 我们可以通过 (implicitly) 调用 `Pin::deref_mut` 来获得这样的引用，但这仅是可能的，因为 `String` 实现了 `Unpin`。
/////
/// mem::replace(&mut *pinned_string, "other".to_string());
/// ```
///
/// trait 几乎针对每种类型自动实现。
///
/// [`mem::replace`]: crate::mem::replace
/// [Pin]: crate::pin::Pin
/// [`pin` module]: crate::pin
///
///
///
///
///
///
#[stable(feature = "pin", since = "1.33.0")]
#[rustc_on_unimplemented(
    note = "consider using `Box::pin`",
    message = "`{Self}` cannot be unpinned"
)]
#[lang = "unpin"]
pub auto trait Unpin {}

/// 没有实现 `Unpin` 的标记类型。
///
/// 如果类型包含 `PhantomPinned`，则默认情况下将不实现 `Unpin`。
#[stable(feature = "pin", since = "1.33.0")]
#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct PhantomPinned;

#[stable(feature = "pin", since = "1.33.0")]
impl !Unpin for PhantomPinned {}

#[stable(feature = "pin", since = "1.33.0")]
impl<'a, T: ?Sized + 'a> Unpin for &'a T {}

#[stable(feature = "pin", since = "1.33.0")]
impl<'a, T: ?Sized + 'a> Unpin for &'a mut T {}

#[stable(feature = "pin_raw", since = "1.38.0")]
impl<T: ?Sized> Unpin for *const T {}

#[stable(feature = "pin_raw", since = "1.38.0")]
impl<T: ?Sized> Unpin for *mut T {}

/// `Copy` 的基本类型的实现。
///
/// `rustc_trait_selection` 中的 `traits::SelectionContext::copy_clone_conditions()` 中实现了 Rust 中无法描述的实现。
///
///
mod copy_impls {

    use super::Copy;

    macro_rules! impl_copy {
        ($($t:ty)*) => {
            $(
                #[stable(feature = "rust1", since = "1.0.0")]
                impl Copy for $t {}
            )*
        }
    }

    impl_copy! {
        usize u8 u16 u32 u64 u128
        isize i8 i16 i32 i64 i128
        f32 f64
        bool char
    }

    #[unstable(feature = "never_type", issue = "35121")]
    impl Copy for ! {}

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Copy for *const T {}

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Copy for *mut T {}

    /// 共享的引用可以复制，但是可变引用 *不能*!
    #[stable(feature = "rust1", since = "1.0.0")]
    impl<T: ?Sized> Copy for &T {}
}