//! 这是一个密集包装的错误表示，用于具有
//! 64 位指针。
//!
//! (请注意，这里的 `bitpacked` 与 `unpacked` 与 `#[repr(packed)]` 没有关系，它只是指尝试以比 `rustc` 的默认布局算法更聪明的方式使用任何可用位)。
//!
//! 从概念上讲，它存储的数据与我们在其他目标上使用的 "unpacked" 等效数据相同。具体来说，您可以将其想象为以下枚举的优化版本 (大致相当于 `repr_unpacked::Repr` 存储的内容，例如
//! `super::ErrorData<Box<Custom>>`):
//!
//! ```ignore (exposition-only)
//! enum ErrorData {
//!    Os(i32),
//!    Simple(ErrorKind),
//!    SimpleMessage(&'static SimpleMessage),
//!    Custom(Box<Custom>),
//! }
//! ```
//!
//! 但是，它将这些数据打包成一个 64 位非零值。
//!
//! 这种优化不仅允许 `io::Error` 占用单个指针，而且还改进了 `io::Result`，尤其是对于像 `io::Result<()>` (现在是 64 位) 或 `io::Result<u64>` (现在
//! 128 位)，这是非常常见的。
//!
//! # Layout
//! 标记值为 64 位，其中 2 个最低有效位用于标记。这意味着有 4 个变体：
//!
//! - **标记 0b00**: 第一个变体相当于 `ErrorData::SimpleMessage`，直接持有一个 `&'static SimpleMessage`。
//!
//!   `SimpleMessage` 具有 >= 4 的对齐方式 (这是通过 `#[repr(align)]` 请求的，并在此文件底部进行静态检查)，这意味着每个 `&'static SimpleMessage` 的两个标记位都应为 0，这意味着它的标记和未标记表示是等效的。
//!
//!
//!   这意味着我们可以跳过标记它，这是必要的，因为这个变体可以从 `const fn` 构造，它可能无法标记指针 (或者至少它会很困难)。
//!
//! - **标记 0b01**: 另一个指针，变体，保存 `ErrorData::Custom` 的数据，其余 62 位用于存储 `Box<Custom>`。`Custom` 也有对齐 >= 4，因此底部两位可自由用于标记。
//!
//!   唯一需要注意的是 `ptr::wrapping_add` 和 `ptr::wrapping_sub` 用于标记指针，而不是按位操作。这应该保留指针的出处，否则会丢失。
//!
//! - **标记 0b10**: 保存 `ErrorData::Os(i32)` 的数据。我们将 `i32` 存储在指针的最高有效 32 位中，并且不使用 `2..32` 位做任何事情。使用前 32 位只是为了让我们轻松恢复具有正确符号的 `i32` 代码。
//!
//! - **标记 0b11**: 保存 `ErrorData::Simple(ErrorKind)` 的数据。这也将 `ErrorKind` 存储在前 32 位中，尽管它几乎没有占用那么多。大多数位在这里都没有使用，但我们还不需要它们来做其他事情。
//!
//! # 使用 `NonNull<()>`
//!
//! 一切都存储在 `NonNull<()>` 中，这很奇怪，但实际上是有目的的。
//!
//! 从概念上讲，您可能会认为这更像是：
//!
//! ```ignore (exposition-only)
//! union Repr {
//!     // 保存整数 (Simple/Os) 变体，并提供对标记位的访问。
//!     //
//!     bits: NonZeroU64,
//!     // 标记为 0，因此未标记存储。
//!     msg: &'static SimpleMessage,
//!     // 标记 (偏移) `Box<Custom>` 指针。
//!     tagged_custom: NonNull<()>,
//! }
//! ```
//!
//! 但是这样做有几个问题:
//!
//! 1. Union 访问等效于转换，因此这种表示需要我们在整数和指针之间至少在一个方向上转换，这可能是 UB (即使不是，编译器可能比显式 ptr -> 更难推理整数运算)。
//!
//! 2.
//! 即使 union 的所有字段都有 niche，union 本身也没有，尽管这在未来可能会改变。这会使 `io::Result<()>` 和 `io::Result<usize>` 之类的东西变得更大，从而破坏了这种 bitpacking 的部分动机。
//!
//! 将所有内容存储在 `NonZeroUsize` (或其他整数) 中对于指针标记来说会更传统一些，但它会丢失出处信息，无法从 `const fn` 构造，并且可能还会遇到其他问题。
//!
//! `NonNull<()>` 似乎是唯一的选择，即使有时使用指针类型来存储可能包含整数的东西是相当奇怪的。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

use super::{Custom, ErrorData, ErrorKind, RawOsError, SimpleMessage};
use alloc::boxed::Box;
use core::marker::PhantomData;
use core::mem::{align_of, size_of};
use core::ptr::{self, NonNull};

// 2 个最低有效位用作标记。
const TAG_MASK: usize = 0b11;
const TAG_SIMPLE_MESSAGE: usize = 0b00;
const TAG_CUSTOM: usize = 0b01;
const TAG_OS: usize = 0b10;
const TAG_SIMPLE: usize = 0b11;

/// 内部表示。
///
/// 有关更多信息，请参见模块文档，这只是一种侵入检查的方式，我们实际上并不安全。
///
///
/// ```compile_fail,E0277
/// fn is_unwind_safe<T: core::panic::UnwindSafe>() {}
/// is_unwind_safe::<std::io::Error>();
/// ```
#[repr(transparent)]
pub(super) struct Repr(NonNull<()>, PhantomData<ErrorData<Box<Custom>>>);

// `Repr` 内部存储的所有类型都是 Send + Sync，它也是如此。
unsafe impl Send for Repr {}
unsafe impl Sync for Repr {}

impl Repr {
    pub(super) fn new(dat: ErrorData<Box<Custom>>) -> Self {
        match dat {
            ErrorData::Os(code) => Self::new_os(code),
            ErrorData::Simple(kind) => Self::new_simple(kind),
            ErrorData::SimpleMessage(simple_message) => Self::new_simple_message(simple_message),
            ErrorData::Custom(b) => Self::new_custom(b),
        }
    }

    pub(super) fn new_custom(b: Box<Custom>) -> Self {
        let p = Box::into_raw(b).cast::<u8>();
        // 只有当分配器分发了一个错误对齐的指针时才可能。
        //
        debug_assert_eq!(p.addr() & TAG_MASK, 0);
        // Note: 我们知道 `TAG_CUSTOM <= size_of::<Custom>()` (文件末尾的 static_assert)，由于 `Box` 的语义，表达式的开头和结尾都必须在没有地址空间环绕的情况下有效。
        //
        //
        // 这意味着使用 `ptr::add` (而不是 `ptr::wrapping_add`) 实现它是正确的，但不清楚这会带来什么好处，所以我们只使用 `wrapping_add`。
        //
        //
        //
        let tagged = p.wrapping_add(TAG_CUSTOM).cast::<()>();
        // 安全性: `TAG_CUSTOM + p` 与 `TAG_CUSTOM | p` 相同，因为 `p` 的对齐方式意味着不允许设置任何 `TAG_BITS` (当操作数没有共同位时，您可以验证加法和按位或相同) 使用真值表)。
        //
        //
        // 然后，`TAG_CUSTOM | p` 不为零，因为这需要 `TAG_CUSTOM` 和 `p` 都为零，而且两者都不是 (因为 `p` 来自 box，而 `TAG_CUSTOM` 只是...
        // 不是零 -- 它是 `0b01`)。
        // 因此，`TAG_CUSTOM + p` 不为零，所以 `tagged` 不能为零，`new_unchecked` 是安全的。
        //
        //
        //
        //
        let res = Self(unsafe { NonNull::new_unchecked(tagged) }, PhantomData);
        // 快速抽烟检查我们编码正确的东西 (这通常只会在 std 的测试中运行，除非用户使用 - Zbuild-std)
        //
        debug_assert!(matches!(res.data(), ErrorData::Custom(_)), "repr(custom) encoding failed");
        res
    }

    #[inline]
    pub(super) fn new_os(code: RawOsError) -> Self {
        let utagged = ((code as usize) << 32) | TAG_OS;
        // 安全性: `TAG_OS` 不为零，所以 `|` 的结果不 0.
        let res = Self(unsafe { NonNull::new_unchecked(ptr::invalid_mut(utagged)) }, PhantomData);
        // 快速抽烟检查我们编码正确的东西 (这通常只会在 std 的测试中运行，除非用户使用 - Zbuild-std)
        //
        debug_assert!(
            matches!(res.data(), ErrorData::Os(c) if c == code),
            "repr(os) encoding failed for {code}"
        );
        res
    }

    #[inline]
    pub(super) fn new_simple(kind: ErrorKind) -> Self {
        let utagged = ((kind as usize) << 32) | TAG_SIMPLE;
        // 安全性: `TAG_SIMPLE` 不为零，所以 `|` 的结果不 0.
        let res = Self(unsafe { NonNull::new_unchecked(ptr::invalid_mut(utagged)) }, PhantomData);
        // 快速抽烟检查我们编码正确的东西 (这通常只会在 std 的测试中运行，除非用户使用 - Zbuild-std)
        //
        debug_assert!(
            matches!(res.data(), ErrorData::Simple(k) if k == kind),
            "repr(simple) encoding failed {:?}",
            kind,
        );
        res
    }

    #[inline]
    pub(super) const fn new_simple_message(m: &'static SimpleMessage) -> Self {
        // 安全性：引用永远不会为空。
        Self(unsafe { NonNull::new_unchecked(m as *const _ as *mut ()) }, PhantomData)
    }

    #[inline]
    pub(super) fn data(&self) -> ErrorData<&Custom> {
        // 安全性：我们是 Repr，decode_repr 很好。
        unsafe { decode_repr(self.0, |c| &*c) }
    }

    #[inline]
    pub(super) fn data_mut(&mut self) -> ErrorData<&mut Custom> {
        // 安全性：我们是 Repr，decode_repr 很好。
        unsafe { decode_repr(self.0, |c| &mut *c) }
    }

    #[inline]
    pub(super) fn into_data(self) -> ErrorData<Box<Custom>> {
        let this = core::mem::ManuallyDrop::new(self);
        // 安全性：我们是 Repr，decode_repr 很好。
        // `Box::from_raw` 是安全的，因为我们使用 `ManuallyDrop` 防止丢弃。
        unsafe { decode_repr(this.0, |p| Box::from_raw(p)) }
    }
}

impl Drop for Repr {
    #[inline]
    fn drop(&mut self) {
        // 安全性：我们是 Repr，decode_repr 很好。
        // `Box::from_raw` 是安全的，因为我们正在被丢弃。
        unsafe {
            let _ = decode_repr(self.0, |p| Box::<Custom>::from_raw(p));
        }
    }
}

// 将 `Repr` 的内部指针解码为 ErrorData 的共享助手。
//
// 安全性: `ptr` 的位应该按照顶部文档中的描述进行编码 (应该是 `some_repr.0`)
//
#[inline]
unsafe fn decode_repr<C, F>(ptr: NonNull<()>, make_custom: F) -> ErrorData<C>
where
    F: FnOnce(*mut Custom) -> C,
{
    let bits = ptr.as_ptr().addr();
    match bits & TAG_MASK {
        TAG_OS => {
            let code = ((bits as i64) >> 32) as RawOsError;
            ErrorData::Os(code)
        }
        TAG_SIMPLE => {
            let kind_bits = (bits >> 32) as u32;
            let kind = kind_from_prim(kind_bits).unwrap_or_else(|| {
                debug_assert!(false, "Invalid io::error::Repr bits: `Repr({:#018x})`", bits);
                // 这意味着传入的 `ptr` 无效，违反了 `decode_repr` 的不安全契约。
                //
                // 使用它而不是展开有意义地改进了只关心一个变体 (通常是 `Custom`) 的调用者的代码
                //
                //
                //
                core::hint::unreachable_unchecked();
            });
            ErrorData::Simple(kind)
        }
        TAG_SIMPLE_MESSAGE => ErrorData::SimpleMessage(&*ptr.cast::<SimpleMessage>().as_ptr()),
        TAG_CUSTOM => {
            // 我们在这里使用 `ptr::byte_sub` 是正确的 (请参见 `new_custom` 中 `wrapping_add` 调用上方的注释了解原因)，但不清楚它是否有区别，所以我们没有。
            //
            //
            let custom = ptr.as_ptr().wrapping_byte_sub(TAG_CUSTOM).cast::<Custom>();
            ErrorData::Custom(make_custom(custom))
        }
        _ => {
            // 这是不可能发生的，编译器可以判断
            unreachable!();
        }
    }
}

// 这将编译为与 check+transmute 相同的代码，但不需要 unsafe，或者以编译器无法验证的方式硬编码 max ErrorKind 或其大小。
//
//
#[inline]
fn kind_from_prim(ek: u32) -> Option<ErrorKind> {
    macro_rules! from_prim {
        ($prim:expr => $Enum:ident { $($Variant:ident),* $(,)? }) => {{
            // 如果列表过期，则强制编译错误。
            const _: fn(e: $Enum) = |e: $Enum| match e {
                $($Enum::$Variant => ()),*
            };
            match $prim {
                $(v if v == ($Enum::$Variant as _) => Some($Enum::$Variant),)*
                _ => None,
            }
        }}
    }
    from_prim!(ek => ErrorKind {
        NotFound,
        PermissionDenied,
        ConnectionRefused,
        ConnectionReset,
        HostUnreachable,
        NetworkUnreachable,
        ConnectionAborted,
        NotConnected,
        AddrInUse,
        AddrNotAvailable,
        NetworkDown,
        BrokenPipe,
        AlreadyExists,
        WouldBlock,
        NotADirectory,
        IsADirectory,
        DirectoryNotEmpty,
        ReadOnlyFilesystem,
        FilesystemLoop,
        StaleNetworkFileHandle,
        InvalidInput,
        InvalidData,
        TimedOut,
        WriteZero,
        StorageFull,
        NotSeekable,
        FilesystemQuotaExceeded,
        FileTooLarge,
        ResourceBusy,
        ExecutableFileBusy,
        Deadlock,
        CrossesDevices,
        TooManyLinks,
        InvalidFilename,
        ArgumentListTooLong,
        Interrupted,
        Other,
        UnexpectedEof,
        Unsupported,
        OutOfMemory,
        Uncategorized,
    })
}

// 一些静态检查提醒我们一个变化是否打破了我们编码所依赖的正确性和可靠性的任何假设。
// (诚然，其中一些有点过于彻底/谨慎)
//
// 如果其中任何一个在 std 支持的平台上发生，我们应该只在那里使用 `repr_unpacked.rs` (除非修复很容易)。
//
//
macro_rules! static_assert {
    ($condition:expr) => {
        const _: () = assert!($condition);
    };
    (@usize_eq: $lhs:expr, $rhs:expr) => {
        const _: [(); $lhs] = [(); $rhs];
    };
}

// 我们使用的位打包要求指针正好是 64 位。
static_assert!(@usize_eq: size_of::<NonNull<()>>(), 8);

// 我们还要求指针和 usize 的大小相同。
static_assert!(@usize_eq: size_of::<NonNull<()>>(), size_of::<usize>());

// `Custom` 和 `SimpleMessage` 需要是瘦指针。
static_assert!(@usize_eq: size_of::<&'static SimpleMessage>(), 8);
static_assert!(@usize_eq: size_of::<Box<Custom>>(), 8);

static_assert!((TAG_MASK + 1).is_power_of_two());
// 它们必须有足够的对齐。
static_assert!(align_of::<SimpleMessage>() >= TAG_MASK + 1);
static_assert!(align_of::<Custom>() >= TAG_MASK + 1);

// `RawOsError` 必须是 `i32` 的别名。
const _: fn(RawOsError) -> i32 = |os| os;

static_assert!(@usize_eq: TAG_MASK & TAG_SIMPLE_MESSAGE, TAG_SIMPLE_MESSAGE);
static_assert!(@usize_eq: TAG_MASK & TAG_CUSTOM, TAG_CUSTOM);
static_assert!(@usize_eq: TAG_MASK & TAG_OS, TAG_OS);
static_assert!(@usize_eq: TAG_MASK & TAG_SIMPLE, TAG_SIMPLE);

// 这显然是正确的 (`TAG_CUSTOM` 是 `0b01`)，但是在 `Repr::new_custom` 中，我们将指针偏移了这个值，并期望它都在同一个 object 内，并且不会环绕地址空间。
// 有关更多详细信息，请参见该函数中的注释。
//
// 实际上，目前我们使用的是 `ptr::wrapping_add`，而不是 `ptr::add`，因此该检查不需要此检查，尽管我们实际上并未在 wrapping_add 中进行回绕的断言确实大大简化了其他地方的安全推理。
//
//
//
//
//
static_assert!(size_of::<Custom>() >= TAG_CUSTOM);

// 这两个函数存储的有效载荷允许为零，因此它们必须为非零以保持 `NonNull` 的范围不变。
//
static_assert!(TAG_OS != 0);
static_assert!(TAG_SIMPLE != 0);
// 我们不能标记 `SimpleMessage`，标记必须是 0.
static_assert!(@usize_eq: TAG_SIMPLE_MESSAGE, 0);

// 检查所有这一切的要点是否仍然成立。
//
// 我们会检查 `io::Error`，但技术上它是允许变化的，因为它不是 `#[repr(transparent)]`/`#[repr(C)]`。
// 我们可以添加它，但 `#[repr()]` 会出现在 rustdoc 中，这可能被视为一个稳定的承诺。
//
//
static_assert!(@usize_eq: size_of::<Repr>(), 8);
static_assert!(@usize_eq: size_of::<Option<Repr>>(), 8);
static_assert!(@usize_eq: size_of::<Result<(), Repr>>(), 8);
static_assert!(@usize_eq: size_of::<Result<usize, Repr>>(), 16);