//! 代表类型基本属性的原始 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。
///
/// 基本语法如下所示:
/// ```ignore private macro
/// marker_impls! { MarkerTrait for u8, i8 }
/// ```
/// 您还可以实现 `unsafe` traits
/// ```ignore private macro
/// marker_impls! { unsafe MarkerTrait for u8, i8 }
/// ```
/// 为所有 impls 添加属性:
/// ```ignore private macro
/// marker_impls! {
///     #[allow(lint)]
///     #[unstable(feature = "marker_trait", issue = "none")]
///     MarkerTrait for u8, i8
/// }
/// ```
/// 并使用泛型:
/// ```ignore private macro
/// marker_impls! {
///     MarkerTrait for
///         u8, i8,
///         {T: ?Sized} *const T,
///         {T: ?Sized} *mut T,
///         {T: MarkerTrait} PhantomData<T>,
///         u32,
/// }
/// ```
#[unstable(feature = "internal_impls_macro", issue = "none")]
macro marker_impls {
    ( $(#[$($meta:tt)*])* $Trait:ident for $({$($bounds:tt)*})? $T:ty $(, $($rest:tt)*)? ) => {
        $(#[$($meta)*])* impl< $($($bounds)*)? > $Trait for $T {}
        marker_impls! { $(#[$($meta)*])* $Trait for $($($rest)*)? }
    },
    ( $(#[$($meta:tt)*])* $Trait:ident for ) => {},

    ( $(#[$($meta:tt)*])* unsafe $Trait:ident for $({$($bounds:tt)*})? $T:ty $(, $($rest:tt)*)? ) => {
        $(#[$($meta)*])* unsafe impl< $($($bounds)*)? > $Trait for $T {}
        marker_impls! { $(#[$($meta)*])* unsafe $Trait for $($($rest)*)? }
    },
    ( $(#[$($meta:tt)*])* unsafe $Trait:ident for ) => {},
}

/// 可以跨线程边界传输的类型。
///
/// 当编译器确定适当时，会自动实现此 trait。
///
/// 非 `Send` 类型的一个例子是引用计数指针 [`rc::Rc`][`Rc`]。
/// 如果两个线程试图克隆指向相同引用计数值的 [`Rc`]，它们可能会同时尝试更新引用计数，这是 [未定义行为][ub] 因为 [`Rc`] 不使用原子操作。
///
/// 它的表亲 [`sync::Arc`][arc] 确实使用原子操作 (产生一些开销)，因此它是 `Send`。
///
/// 有关详细信息，请参见 [the Nomicon](../../nomicon/send-and-sync.html) 和 [`Sync`] trait。
///
/// [`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")]
#[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 {}

// 大多数实例会自动出现，但需要此实例将 `T: Sync` 与 `&T: Send` 链接起来 (并且它还删除了不合理的默认实例 `T Send` -> `&T: Send` 否则会存在)。
//
//
#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Sync + ?Sized> Send for &T {}

/// 在编译时已知大小为常量的类型。
///
/// 所有类型参数都有一个 `Sized` 的隐式界限。如果不合适，可以使用特殊语法 `?Sized` 删除这个界限。
///
/// ```
/// # #![allow(dead_code)]
/// struct Foo<T>(T);
/// struct Bar<T: ?Sized>(T);
///
/// // struct FooUse(Foo<[i32]>);  // 错误：没有为 [i32] 实现 Sized
/// 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;  // 错误：无法将 `Bar` trait 制作成对象
/////
/// ```
///
/// [trait object]: ../../book/ch17-02-trait-objects.html
///
///
///
#[doc(alias = "?", alias = "?Sized")]
#[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]
#[rustc_deny_explicit_impl]
#[rustc_coinductive]
pub trait Sized {
    // Empty.
}

/// 可以把没有大小的类型改为动态大小的类型。
///
/// 例如，按大小排列的数组类型 `[i8; 2]` 实现 `Unsize<[i8]>` 和 `Unsize<dyn fmt::Debug>`。
///
/// `Unsize` 的所有实现都是由编译器自动提供的。
/// 这些实现是：
///
/// - Arrays `[T; N]` implement `Unsize<[T]>`.
/// - 实现 `Trait` trait 的类型也实现了 `Unsize<dyn Trait>`。
/// - 结构体 `Foo<..., T, ...>` 实现了 `Unsize<Foo<..., U, ...>>` 如果所有这些条件都满足：
///   - `T: Unsize<U>`.
///   - 只有 `Foo` 的最后一个字段具有包含 `T` 的类型。
///   - `Bar<T>: Unsize<Bar<U>>`，其中 `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 = "18598")]
#[lang = "unsize"]
#[rustc_deny_explicit_impl]
pub trait Unsize<T: ?Sized> {
    // Empty.
}

/// 模式匹配中使用的常量的必需 trait。
///
/// 不管其类型参数是否实现了 `Eq`，任何派生 `PartialEq` 的类型都会自动实现这个 trait。
///
/// 如果 `const` 项包含某种不实现此 trait 的类型，则该类型要么 (1.) 不实现 `PartialEq` (这意味着常量将不提供该比较方法 (代码生成假定可用) )，要么 (2.) 自身实现 *its*`PartialEq` 的版本 (我们认为不符合结构相等性比较)。
///
///
/// 在以上两种情况中的任何一种情况下，我们都拒绝在模式匹配中使用此类常量。
///
/// 另请参见 [结构匹配 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.
}

// FIXME: 从编译器模式检查代码中删除这些类型的特殊情况，并始终检查 `T: StructuralEq`
marker_impls! {
    #[unstable(feature = "structural_match", issue = "31434")]
    StructuralEq for
        usize, u8, u16, u32, u64, u128,
        isize, i8, i16, i32, i64, i128,
        bool,
        char,
        str /* Technically requires `[u8]: StructuralEq` */,
        {T, const N: usize} [T; N],
        {T} [T],
        {T: ?Sized} &T,
}

/// 只需复制位即可复制其值的类型。
///
/// 默认情况下，变量绑定具有移动语义。换句话说：
///
/// ```
/// #[derive(Debug)]
/// struct Foo;
///
/// let x = Foo;
///
/// let y = x;
///
/// // `x` 已移入 `y`，因此无法使用
///
/// // println!("{x:?}"); // error: use of moved value
/// ```
///
/// 但是，如果类型实现 `Copy`，则它具有复制语义：
///
/// ```
/// // 我们可以派生一个 `Copy` 实现。
/// // `Clone` 也是必需的，因为它是 `Copy` 的 super trait。
/// #[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` 有什么区别？
///
/// Copy 是隐式发生的，例如作为赋值 `y = x` 的一部分。`Copy` 的行为不可重载； 它始终是简单的按位复制。
///
/// Clone 是一个显式操作，`x.clone()`。[`Clone`] 的实现可以提供安全复制值所需的任何特定于类型的行为。
/// 例如，用于 [`String`] 的 [`Clone`] 的实现需要在堆中复制指向字符串的缓冲区。
/// [`String`] 值的简单按位副本将仅复制指针，从而导致该行向下双重释放。
/// 因此，[`String`] 是 [`Clone`]，但不是 `Copy`。
///
/// [`Clone`] 是 `Copy` 的一个 super trait，所以所有 `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` cannot 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_codes/E0204.html
///
/// ## 什么时候我的类型应该是 `Copy`？
///
/// 一般来说，如果您的类型可以实现 `Copy`，则应该这样做。
/// 但是请记住，实现 `Copy` 是您类型的公共 API 的一部分。
/// 如果该类型将来可能变为非 `Copy`，则最好现在省略 `Copy` 实现，以避免 API 发生重大更改。
///
/// ## 其他实现者
///
/// 除 [下面列出的实现者][impls] 之外，以下类型也实现了 `Copy`：
///
/// * 函数项类型 (即，为每个函数定义的不同类型)
/// * 函数指针类型 (例如 `fn() -> i32`)
/// * 闭包类型，如果它们没有从环境中捕获任何值，或者所有此类捕获的值本身都实现了 `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]
#[rustc_diagnostic_item = "Copy"]
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 */
}

// 原始类型的 `Copy` 实现。
//
// `rustc_trait_selection` 中的 `traits::SelectionContext::copy_clone_conditions()` 中实现了 Rust 中无法描述的实现。
//
//
marker_impls! {
    #[stable(feature = "rust1", since = "1.0.0")]
    Copy for
        usize, u8, u16, u32, u64, u128,
        isize, i8, i16, i32, i64, i128,
        f32, f64,
        bool, char,
        {T: ?Sized} *const T,
        {T: ?Sized} *mut T,

}

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

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

/// 可以在线程之间安全共享引用的类型。
///
/// 当编译器确定适当时，会自动实现此 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`] 和 [`Send`] 与引用的关系的简短概述:
/// * `&T` 是 [`Send`] 当且仅当 `T` 是 [`Sync`]
/// * `&mut T` 是 [`Send`] 当且仅当 `T` 是 [`Send`]
/// * `&T` 和 `&mut T` 是 [`Sync`] 当且仅当 `T` 是 [`Sync`]
///
/// 不是 `Sync` 的类型是具有非线程安全形式的 "内部可变性" 的类型，例如 [`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] 的线程安全模拟。
///
/// 任何具有内部可变性的类型还必须在值周围使用 [`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")]
#[lang = "sync"]
#[rustc_on_unimplemented(
    on(
        _Self = "std::cell::OnceCell<T>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::OnceLock` instead"
    ),
    on(
        _Self = "std::cell::Cell<u8>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU8` instead",
    ),
    on(
        _Self = "std::cell::Cell<u16>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU16` instead",
    ),
    on(
        _Self = "std::cell::Cell<u32>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU32` instead",
    ),
    on(
        _Self = "std::cell::Cell<u64>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU64` instead",
    ),
    on(
        _Self = "std::cell::Cell<usize>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicUsize` instead",
    ),
    on(
        _Self = "std::cell::Cell<i8>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI8` instead",
    ),
    on(
        _Self = "std::cell::Cell<i16>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI16` instead",
    ),
    on(
        _Self = "std::cell::Cell<i32>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI32` instead",
    ),
    on(
        _Self = "std::cell::Cell<i64>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI64` instead",
    ),
    on(
        _Self = "std::cell::Cell<isize>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicIsize` instead",
    ),
    on(
        _Self = "std::cell::Cell<bool>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicBool` instead",
    ),
    on(
        _Self = "std::cell::Cell<T>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock`",
    ),
    on(
        _Self = "std::cell::RefCell<T>",
        note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` instead",
    ),
    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` 中添加注释登陆 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 {}

/// 零大小的类型用来标记那些行为像它们拥有一个 `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> {
///     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> {
/// #     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` 与丢弃检查的确切交互**可能会在 future**中发生变化。
///
/// 目前，添加 `PhantomData<T>` 类型的字段表示在极少数情况下您的类型*拥有*`T` 类型的数据。
/// 这反过来又会影响 Rust 编译器的 [drop check] 分析。
/// 有关确切规则，请参见 [drop check] 文档。
///
/// ## Layout
///
/// 对于所有 `T`，保证以下内容:
/// * `size_of::<PhantomData<T>>() == 0`
/// * `align_of::<PhantomData<T>>() == 1`
///
/// [drop check]: Drop#drop-check
///
///
///
///
///
///
///
///
///
///
///
///
///
#[lang = "phantom_data"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct PhantomData<T: ?Sized>;

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

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

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

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

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

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

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

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

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

#[unstable(feature = "structural_match", issue = "31434")]
impl<T: ?Sized> StructuralEq for PhantomData<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"]
#[rustc_deny_explicit_impl]
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> {}
marker_impls! {
    unsafe Freeze for
        {T: ?Sized} PhantomData<T>,
        {T: ?Sized} *const T,
        {T: ?Sized} *mut T,
        {T: ?Sized} &T,
        {T: ?Sized} &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 the `pin!` macro\nconsider using `Box::pin` if you need to access the pinned value outside of the current scope",
    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 {}

marker_impls! {
    #[stable(feature = "pin", since = "1.33.0")]
    Unpin for
        {T: ?Sized} &T,
        {T: ?Sized} &mut T,
}

marker_impls! {
    #[stable(feature = "pin_raw", since = "1.38.0")]
    Unpin for
        {T: ?Sized} *const T,
        {T: ?Sized} *mut T,
}

/// 可以丢弃的类型的标记。
///
/// 这应该用于 `~const` 边界，因为非常量边界将始终适用于每种类型。
///
#[unstable(feature = "const_trait_impl", issue = "67792")]
#[lang = "destruct"]
#[rustc_on_unimplemented(message = "can't drop `{Self}`", append_const_msg)]
#[rustc_deny_explicit_impl]
#[const_trait]
pub trait Destruct {}

/// 元组类型的标记。
///
/// 这个 trait 的实现是内置的，不能为任何用户类型实现。
///
#[unstable(feature = "tuple_trait", issue = "none")]
#[lang = "tuple_trait"]
#[rustc_on_unimplemented(message = "`{Self}` is not a tuple")]
#[rustc_deny_explicit_impl]
pub trait Tuple {}

/// 类指针类型的标记。
///
/// 所有与 `usize` 或 `*const ()` 具有相同大小和对齐方式的类型都会自动实现此 trait。
///
#[unstable(feature = "pointer_like_trait", issue = "none")]
#[lang = "pointer_like"]
#[rustc_on_unimplemented(
    message = "`{Self}` needs to have the same ABI as a pointer",
    label = "`{Self}` needs to be a pointer-like type"
)]
pub trait PointerLike {}

/// 可用作 `const` 泛型参数类型的类型的标记。
#[cfg_attr(not(bootstrap), lang = "const_param_ty")]
#[unstable(feature = "adt_const_params", issue = "95174")]
#[rustc_on_unimplemented(message = "`{Self}` can't be used as a const parameter type")]
pub trait ConstParamTy: StructuralEq {}

/// 派生宏生成 trait `ConstParamTy` 的一个 impl。
#[rustc_builtin_macro]
#[unstable(feature = "adt_const_params", issue = "95174")]
#[cfg(not(bootstrap))]
pub macro ConstParamTy($item:item) {
    /* compiler built-in */
}

// FIXME(generic_const_parameter_types): 句柄 `ty::FnDef`/`ty::Closure`
// FIXME(generic_const_parameter_types): 句柄 `ty::Tuple`
marker_impls! {
    #[unstable(feature = "adt_const_params", issue = "95174")]
    ConstParamTy for
        usize, u8, u16, u32, u64, u128,
        isize, i8, i16, i32, i64, i128,
        bool,
        char,
        str /* Technically requires `[u8]: ConstParamTy` */,
        {T: ConstParamTy, const N: usize} [T; N],
        {T: ConstParamTy} [T],
        {T: ?Sized + ConstParamTy} &T,
}

/// 由所有函数指针实现的公共 trait。
#[unstable(
    feature = "fn_ptr_trait",
    issue = "none",
    reason = "internal trait for implementing various traits for all function pointers"
)]
#[lang = "fn_ptr_trait"]
#[rustc_deny_explicit_impl]
pub trait FnPtr: Copy + Clone {
    /// 返回函数指针的地址。
    #[lang = "fn_ptr_addr"]
    fn addr(self) -> *const ();
}