//! 单线程引用计数指针。`Rc` 代表引用计数。
//!
//! [`Rc<T>`][`Rc`] 类型提供了在堆中分配的 `T` 类型值的共享所有权。
//! 在 [`Rc`] 上调用 [`clone`][clone] 会产生一个指向堆中相同分配的新指针。
//! 当指向给定分配的最后一个 [`Rc`] 指针被销毁时，存储在该分配中的值 (通常称为 "内部值") 也将被丢弃。
//!
//! 默认情况下，Rust 中的共享引用不允许可变的，[`Rc`] 也不例外: 您通常无法获得 [`Rc`] 内部内容的可变引用。
//! 如果需要可变性，则将 [`Cell`] 或 [`RefCell`] 放在 [`Rc`] 内; 请参见 [`Rc` 中的可变性示例][mutability]。
//!
//! [`Rc`] 使用非原子引用计数。
//! 这意味着开销非常低，但是 [`Rc`] 无法在线程之间发送，因此 [`Rc`] 无法实现 [`Send`][send]。
//! 结果，Rust 编译器将检查 *at compile time* 您是否不在线程之间发送 [`Rc`]。
//! 如果需要多线程的原子引用计数，请使用 [`sync::Arc`][arc]。
//!
//! [`downgrade`][downgrade] 方法可用于创建非所有者 [`Weak`] 指针。
//! [`Weak`] 指针可以被 [`upgrade`][upgrade] 到 [`Rc`]，但是如果已经丢弃了分配中存储的值，则它将返回 [`None`]。
//! 换句话说，`Weak` 指针不会使分配内部的值保持活动状态。但是，它们确实使分配 (内部值的后备存储) 保持活动状态。
//!
//! [`Rc`] 指针之间的循环将永远不会被释放。
//! 因此，[`Weak`] 用于中断循环。
//! 例如，一棵树可以具有从父节点到子节点的强 [`Rc`] 指针，以及从子节点到其父节点的 [`Weak`] 指针。
//!
//! `Rc<T>` 自动取消对 `T` 的引用 (通过 [`Deref`] trait)，因此您可以在 [`Rc<T>`][`Rc`] 类型的值上调用 `T` 的方法。
//! 为了避免与 T 方法的名称冲突，[`Rc<T>`][`Rc`] 本身的方法是关联函数，使用 [fully qualified syntax] 进行调用:
//!
//! ```
//! use std::rc::Rc;
//!
//! let my_rc = Rc::new(());
//! Rc::downgrade(&my_rc);
//! ```
//!
//! `RC<T> 也可以使用完全限定语法来调用 traits 的 `Clone` 等实现。
//! 有些人喜欢使用完全限定的语法，而另一些人则喜欢使用方法调用语法。
//!
//! ```
//! use std::rc::Rc;
//!
//! let rc = Rc::new(());
//! // 方法调用语法
//! let rc2 = rc.clone();
//! // 完全限定的语法
//! let rc3 = Rc::clone(&rc);
//! ```
//!
//! [`Weak<T>`][`Weak`] 不会自动解引用到 `T`，因为内部值可能已被丢弃。
//!
//! # 克隆引用
//!
//! 使用为 [`Rc<T>`][`Rc`] 和 [`Weak<T>`][`Weak`] 实现的 `Clone` trait，可以创建与现有引用计数指针相同分配的新引用。
//!
//!
//! ```
//! use std::rc::Rc;
//!
//! let foo = Rc::new(vec![1.0, 2.0, 3.0]);
//! // 以下两种语法是等效的。
//! let a = foo.clone();
//! let b = Rc::clone(&foo);
//! // a 和 b 都指向与 foo 相同的内存位置。
//! ```
//!
//! `Rc::clone(&from)` 语法是最常见的语法，因为它更明确地传达了代码的含义。
//! 在上面的示例中，使用此语法可以更轻松地看到此代码正在创建新的引用，而不是复制 foo 的全部内容。
//!
//! # Examples
//!
//! 考虑一个场景，其中给定的 `Owner` 拥有一组 `Gadget`。
//! 我们想让我们的 `Gadget` 指向他们的 `Owner`。我们不能用唯一的所有权来做到这一点，因为一个以上的 gadget 可能属于同一个 `Owner`。
//! [`Rc`] 允许我们在多个 `Gadget` 之间共享 `Owner`，并且只要 `Gadget` 指向它，`Owner` 就会一直分配。
//!
//! ```
//! use std::rc::Rc;
//!
//! struct Owner {
//!     name: String,
//!     // ... 其他领域
//! }
//!
//! struct Gadget {
//!     id: i32,
//!     owner: Rc<Owner>,
//!     // ... 其他领域
//! }
//!
//! fn main() {
//!     // 创建一个引用计数的 `Owner`。
//!     let gadget_owner: Rc<Owner> = Rc::new(
//!         Owner {
//!             name: "Gadget Man".to_string(),
//!         }
//!     );
//!
//!     // 创建属于 `gadget_owner` 的 `Gadget`。
//!     // 克隆 `Rc<Owner>` 为我们提供了指向同一个 `Owner` 分配的新指针，从而增加了该进程中的引用计数。
//!     //
//!     let gadget1 = Gadget {
//!         id: 1,
//!         owner: Rc::clone(&gadget_owner),
//!     };
//!     let gadget2 = Gadget {
//!         id: 2,
//!         owner: Rc::clone(&gadget_owner),
//!     };
//!
//!     // 处理我们的局部变量 `gadget_owner`。
//!     drop(gadget_owner);
//!
//!     // 尽管丢弃了 `gadget_owner`，我们仍然可以打印出 `Gadget` 的 `Owner` 的名称。
//!     // 这是因为我们只删除了一个 `Rc<Owner>`，而不是它指向的 `Owner`。
//!     // 只要还有其他 `Rc<Owner>` 指向相同的 `Owner` 分配，它将保持活动状态。
//!     // 字段投影 `gadget1.owner.name` 之所以起作用，是因为 `Rc<Owner>` 自动取消了对 `Owner` 的引用。
//!     //
//!     //
//!     println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name);
//!     println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name);
//!
//!     // 在该函数的末尾，`gadget1` 和 `gadget2` 被销毁，并且它们与我们的 `Owner` 一起被算作最后引用。
//!     // `Gadget` 现在也被摧毁。
//!     //
//! }
//! ```
//!
//! 如果我们的要求发生变化，并且还需要能够从 `Owner` 遍历到 `Gadget`，我们将遇到问题。
//! 从 `Owner` 到 `Gadget` 的 [`Rc`] 指针引入了一个循环。
//! 这意味着它们的引用计数永远不会达到 0，并且分配也永远不会被销毁:
//! 内存泄漏。为了解决这个问题，我们可以使用 [`Weak`] 指针。
//!
//! 实际上，Rust 使得在某种程度上很难产生此循环。为了最终得到两个指向彼此的值，其中之一必须是可变的。
//! 这很困难，因为 [`Rc`] 仅通过对其包装的值给出共享的引用来强制执行内存安全性，而这些不允许直接更改。
//! 我们需要将希望可变的的部分值包装在 [`RefCell`] 中，该值提供 *interior 可变性*: 一种通过共享引用实现可变性的方法。
//! [`RefCell`] 在运行时强制执行 Rust 的借用规则。
//!
//! ```
//! use std::rc::Rc;
//! use std::rc::Weak;
//! use std::cell::RefCell;
//!
//! struct Owner {
//!     name: String,
//!     gadgets: RefCell<Vec<Weak<Gadget>>>,
//!     // ... 其他领域
//! }
//!
//! struct Gadget {
//!     id: i32,
//!     owner: Rc<Owner>,
//!     // ... 其他领域
//! }
//!
//! fn main() {
//!     // 创建一个引用计数的 `Owner`。
//!     // 请注意，我们已将 `Gadget` 的所有者的 vector 放在 `RefCell` 内，以便我们可以通过共享的引用对其进行可变。
//!     //
//!     let gadget_owner: Rc<Owner> = Rc::new(
//!         Owner {
//!             name: "Gadget Man".to_string(),
//!             gadgets: RefCell::new(vec![]),
//!         }
//!     );
//!
//!     // 如前所述，创建属于 `gadget_owner` 的 `Gadget`。
//!     let gadget1 = Rc::new(
//!         Gadget {
//!             id: 1,
//!             owner: Rc::clone(&gadget_owner),
//!         }
//!     );
//!     let gadget2 = Rc::new(
//!         Gadget {
//!             id: 2,
//!             owner: Rc::clone(&gadget_owner),
//!         }
//!     );
//!
//!     // 将 `Gadget` 添加到其 `Owner` 中。
//!     {
//!         let mut gadgets = gadget_owner.gadgets.borrow_mut();
//!         gadgets.push(Rc::downgrade(&gadget1));
//!         gadgets.push(Rc::downgrade(&gadget2));
//!
//!         // `RefCell` 动态的借用到此结束。
//!     }
//!
//!     // 遍历我们的 `Gadget`，将其详细信息打印出来。
//!     for gadget_weak in gadget_owner.gadgets.borrow().iter() {
//!
//!         // `gadget_weak` 是 `Weak<Gadget>`。
//!         // 由于 `Weak` 指针不能保证分配仍然存在，因此我们需要调用 `upgrade`，它返回 `Option<Rc<Gadget>>`。
//!         //
//!         //
//!         // 在这种情况下，我们知道分配仍然存在，因此我们只用 `unwrap` 和 `Option`。
//!         // 在更复杂的程序中，可能需要适当的错误处理才能获得 `None` 结果。
//!         //
//!
//!         let gadget = gadget_weak.upgrade().unwrap();
//!         println!("Gadget {} owned by {}", gadget.id, gadget.owner.name);
//!     }
//!
//!     // 在该函数的末尾，`gadget_owner`，`gadget1` 和 `gadget2` 被销毁。
//!     // 现在没有指向该 `Gadget` 的强大 (`Rc`) 指针，因此它们已被销毁。
//!     // 这会使 Gadget Man 的引用计数为零，因此他也被销毁了。
//!     //
//! }
//! ```
//!
//! [clone]: Clone::clone
//! [`Cell`]: core::cell::Cell
//! [`RefCell`]: core::cell::RefCell
//! [send]: core::marker::Send
//! [arc]: crate::sync::Arc
//! [`Deref`]: core::ops::Deref
//! [downgrade]: Rc::downgrade
//! [upgrade]: Weak::upgrade
//! [mutability]: core::cell#introducing-mutability-inside-of-something-immutable
//! [fully qualified syntax]: https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

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

#[cfg(not(test))]
use crate::boxed::Box;
#[cfg(test)]
use std::boxed::Box;

use core::any::Any;
use core::borrow;
use core::cell::Cell;
use core::cmp::Ordering;
use core::convert::{From, TryFrom};
use core::fmt;
use core::hash::{Hash, Hasher};
use core::intrinsics::abort;
#[cfg(not(no_global_oom_handling))]
use core::iter;
use core::marker::{self, PhantomData, Unpin, Unsize};
#[cfg(not(no_global_oom_handling))]
use core::mem::size_of_val;
use core::mem::{self, align_of_val_raw, forget};
use core::ops::{CoerceUnsized, Deref, DispatchFromDyn, Receiver};
#[cfg(not(no_global_oom_handling))]
use core::pin::Pin;
use core::ptr::{self, NonNull};
#[cfg(not(no_global_oom_handling))]
use core::slice::from_raw_parts_mut;

#[cfg(not(no_global_oom_handling))]
use crate::alloc::handle_alloc_error;
#[cfg(not(no_global_oom_handling))]
use crate::alloc::{box_free, WriteCloneIntoRaw};
use crate::alloc::{AllocError, Allocator, Global, Layout};
use crate::borrow::{Cow, ToOwned};
#[cfg(not(no_global_oom_handling))]
use crate::string::String;
#[cfg(not(no_global_oom_handling))]
use crate::vec::Vec;

#[cfg(test)]
mod tests;

// 这是 repr(C) 为了防止未来可能的字段重新排序，否则可能会干扰可安全转换的内部类型的 _raw () 的安全性。
//
//
#[repr(C)]
struct RcBox<T: ?Sized> {
    strong: Cell<usize>,
    weak: Cell<usize>,
    value: T,
}

/// 单线程引用计数指针。`Rc` 代表引用计数。
///
/// 有关更多详细信息，请参见 [模块级文档](./index.html)。
///
/// `Rc` 的固有方法都是关联函数，这意味着您必须以例如 [`Rc::get_mut(&mut value)`][get_mut] 而不是 `value.get_mut()` 的方式调用它们。
/// 这样可以避免与内部类型 `T` 的方法发生冲突。
///
/// [get_mut]: Rc::get_mut
///
///
#[cfg_attr(not(test), rustc_diagnostic_item = "Rc")]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Rc<T: ?Sized> {
    ptr: NonNull<RcBox<T>>,
    phantom: PhantomData<RcBox<T>>,
}

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

#[unstable(feature = "coerce_unsized", issue = "27732")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Rc<U>> for Rc<T> {}

#[unstable(feature = "dispatch_from_dyn", issue = "none")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Rc<U>> for Rc<T> {}

impl<T: ?Sized> Rc<T> {
    #[inline(always)]
    fn inner(&self) -> &RcBox<T> {
        // 这种不安全性是可以的，因为在此 Rc 处于活动状态时，我们保证内部指针有效。
        //
        unsafe { self.ptr.as_ref() }
    }

    fn from_inner(ptr: NonNull<RcBox<T>>) -> Self {
        Self { ptr, phantom: PhantomData }
    }

    unsafe fn from_ptr(ptr: *mut RcBox<T>) -> Self {
        Self::from_inner(unsafe { NonNull::new_unchecked(ptr) })
    }
}

impl<T> Rc<T> {
    /// 创建一个新的 `Rc<T>`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new(value: T) -> Rc<T> {
        // 所有强指针都拥有一个隐式的弱指针，以确保即使强指针中存储了弱指针，弱析构函数也不会在强析构函数运行时释放分配。
        //
        //
        //
        Self::from_inner(
            Box::leak(box RcBox { strong: Cell::new(1), weak: Cell::new(1), value }).into(),
        )
    }

    /// 使用对自身的弱引用创建一个新的 `Rc<T>`。
    /// 在此函数返回之前尝试升级弱引用将得到 `None` 值。
    ///
    /// 但是，弱引用可以自由克隆并存储以备后用。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(arc_new_cyclic)]
    /// #![allow(dead_code)]
    /// use std::rc::{Rc, Weak};
    ///
    /// struct Gadget {
    ///     self_weak: Weak<Self>,
    ///     // ... 更多领域
    /// }
    /// impl Gadget {
    ///     pub fn new() -> Rc<Self> {
    ///         Rc::new_cyclic(|self_weak| {
    ///             Gadget { self_weak: self_weak.clone(), /* ... */ }
    ///         })
    ///     }
    /// }
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "arc_new_cyclic", issue = "75861")]
    pub fn new_cyclic(data_fn: impl FnOnce(&Weak<T>) -> T) -> Rc<T> {
        // 在未初始化状态下用一个弱引用建造内部。
        //
        let uninit_ptr: NonNull<_> = Box::leak(box RcBox {
            strong: Cell::new(0),
            weak: Cell::new(1),
            value: mem::MaybeUninit::<T>::uninit(),
        })
        .into();

        let init_ptr: NonNull<RcBox<T>> = uninit_ptr.cast();

        let weak = Weak { ptr: init_ptr };

        // 重要的是我们不要放弃弱指针的所有权，否则在 `data_fn` 返回时可能会释放内存。
        // 如果我们真的想传递所有权，则可以为我们自己创建一个额外的弱指针，但这将导致对弱引用计数的其他更新，否则可能没有必要。
        //
        //
        //
        //
        let data = data_fn(&weak);

        unsafe {
            let inner = init_ptr.as_ptr();
            ptr::write(ptr::addr_of_mut!((*inner).value), data);

            let prev_value = (*inner).strong.get();
            debug_assert_eq!(prev_value, 0, "No prior strong references should exist");
            (*inner).strong.set(1);
        }

        let strong = Rc::from_inner(init_ptr);

        // 强引用应该共同拥有一个共享的弱引用，所以不要为我们的旧弱引用运行析构函数。
        //
        mem::forget(weak);
        strong
    }

    /// 创建一个具有未初始化内容的新 `Rc`。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut five = Rc::<u32>::new_uninit();
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
    ///
    ///     five.assume_init()
    /// };
    ///
    /// assert_eq!(*five, 5)
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn new_uninit() -> Rc<mem::MaybeUninit<T>> {
        unsafe {
            Rc::from_ptr(Rc::allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate(layout),
                |mem| mem as *mut RcBox<mem::MaybeUninit<T>>,
            ))
        }
    }

    /// 创建一个具有未初始化内容的新 `Rc`，并用 `0` 字节填充内存。
    ///
    ///
    /// 有关正确和不正确使用此方法的示例，请参见 [`MaybeUninit::zeroed`][zeroed]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    ///
    /// use std::rc::Rc;
    ///
    /// let zero = Rc::<u32>::new_zeroed();
    /// let zero = unsafe { zero.assume_init() };
    ///
    /// assert_eq!(*zero, 0)
    /// ```
    ///
    /// [zeroed]: mem::MaybeUninit::zeroed
    ///
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn new_zeroed() -> Rc<mem::MaybeUninit<T>> {
        unsafe {
            Rc::from_ptr(Rc::allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate_zeroed(layout),
                |mem| mem as *mut RcBox<mem::MaybeUninit<T>>,
            ))
        }
    }

    /// 创建一个新的 `Rc<T>`，如果分配失败，则返回错误
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api)]
    /// use std::rc::Rc;
    ///
    /// let five = Rc::try_new(5);
    /// # Ok::<(), std::alloc::AllocError>(())
    /// ```
    #[unstable(feature = "allocator_api", issue = "32838")]
    pub fn try_new(value: T) -> Result<Rc<T>, AllocError> {
        // 所有强指针都拥有一个隐式的弱指针，以确保即使强指针中存储了弱指针，弱析构函数也不会在强析构函数运行时释放分配。
        //
        //
        //
        Ok(Self::from_inner(
            Box::leak(Box::try_new(RcBox { strong: Cell::new(1), weak: Cell::new(1), value })?)
                .into(),
        ))
    }

    /// 用未初始化的内容构造一个新的 `Rc`，如果分配失败，则返回错误
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api, new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut five = Rc::<u32>::try_new_uninit()?;
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
    ///
    ///     five.assume_init()
    /// };
    ///
    /// assert_eq!(*five, 5);
    /// # Ok::<(), std::alloc::AllocError>(())
    /// ```
    #[unstable(feature = "allocator_api", issue = "32838")]
    // #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn try_new_uninit() -> Result<Rc<mem::MaybeUninit<T>>, AllocError> {
        unsafe {
            Ok(Rc::from_ptr(Rc::try_allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate(layout),
                |mem| mem as *mut RcBox<mem::MaybeUninit<T>>,
            )?))
        }
    }

    /// 创建一个具有未初始化内容的新 `Rc`，并用 `0` 字节填充内存，如果分配失败，则返回错误
    ///
    ///
    /// 有关正确和不正确使用此方法的示例，请参见 [`MaybeUninit::zeroed`][zeroed]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api, new_uninit)]
    ///
    /// use std::rc::Rc;
    ///
    /// let zero = Rc::<u32>::try_new_zeroed()?;
    /// let zero = unsafe { zero.assume_init() };
    ///
    /// assert_eq!(*zero, 0);
    /// # Ok::<(), std::alloc::AllocError>(())
    /// ```
    ///
    /// [zeroed]: mem::MaybeUninit::zeroed
    ///
    #[unstable(feature = "allocator_api", issue = "32838")]
    // #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn try_new_zeroed() -> Result<Rc<mem::MaybeUninit<T>>, AllocError> {
        unsafe {
            Ok(Rc::from_ptr(Rc::try_allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate_zeroed(layout),
                |mem| mem as *mut RcBox<mem::MaybeUninit<T>>,
            )?))
        }
    }
    /// 创建一个新的 `Pin<Rc<T>>`。
    /// 如果 `T` 未实现 `Unpin`，则 `value` 将被固定在内存中并且无法移动。
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "pin", since = "1.33.0")]
    pub fn pin(value: T) -> Pin<Rc<T>> {
        unsafe { Pin::new_unchecked(Rc::new(value)) }
    }

    /// 如果 `Rc` 正好有一个强引用，则返回内部值。
    ///
    /// 否则，返回的 [`Err`] 将与传入的 `Rc` 相同。
    ///
    ///
    /// 即使存在突出的弱引用，此操作也将成功。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let x = Rc::new(3);
    /// assert_eq!(Rc::try_unwrap(x), Ok(3));
    ///
    /// let x = Rc::new(4);
    /// let _y = Rc::clone(&x);
    /// assert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4);
    /// ```
    #[inline]
    #[stable(feature = "rc_unique", since = "1.4.0")]
    pub fn try_unwrap(this: Self) -> Result<T, Self> {
        if Rc::strong_count(&this) == 1 {
            unsafe {
                let val = ptr::read(&*this); // 复制包含的对象

                // 向 Weaks 表明，不能通过减少强引用计数来提升它们，然后丢弃隐式 "strong weak" 指针，同时还通过伪造 Weak 来处理放置逻辑。
                //
                //
                //
                this.inner().dec_strong();
                let _weak = Weak { ptr: this.ptr };
                forget(this);
                Ok(val)
            }
        } else {
            Err(this)
        }
    }
}

impl<T> Rc<[T]> {
    /// 创建一个新的带有未初始化内容的引用计数的切片。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut values = Rc::<[u32]>::new_uninit_slice(3);
    ///
    /// let values = unsafe {
    ///     // 延迟初始化:
    ///     Rc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
    ///     Rc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
    ///     Rc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
    ///
    ///     values.assume_init()
    /// };
    ///
    /// assert_eq!(*values, [1, 2, 3])
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn new_uninit_slice(len: usize) -> Rc<[mem::MaybeUninit<T>]> {
        unsafe { Rc::from_ptr(Rc::allocate_for_slice(len)) }
    }

    /// 用未初始化的内容创建一个新的带有引用计数的切片，内存中填充 `0` 字节。
    ///
    ///
    /// 有关正确和不正确使用此方法的示例，请参见 [`MaybeUninit::zeroed`][zeroed]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    ///
    /// use std::rc::Rc;
    ///
    /// let values = Rc::<[u32]>::new_zeroed_slice(3);
    /// let values = unsafe { values.assume_init() };
    ///
    /// assert_eq!(*values, [0, 0, 0])
    /// ```
    ///
    /// [zeroed]: mem::MaybeUninit::zeroed
    ///
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    pub fn new_zeroed_slice(len: usize) -> Rc<[mem::MaybeUninit<T>]> {
        unsafe {
            Rc::from_ptr(Rc::allocate_for_layout(
                Layout::array::<T>(len).unwrap(),
                |layout| Global.allocate_zeroed(layout),
                |mem| {
                    ptr::slice_from_raw_parts_mut(mem as *mut T, len)
                        as *mut RcBox<[mem::MaybeUninit<T>]>
                },
            ))
        }
    }
}

impl<T> Rc<mem::MaybeUninit<T>> {
    /// 转换为 `Rc<T>`。
    ///
    /// # Safety
    ///
    /// 与 [`MaybeUninit::assume_init`] 一样，由调用方负责确保内部值确实处于初始化状态。
    ///
    /// 在内容尚未完全初始化时调用此方法会立即导致未定义的行为。
    ///
    /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut five = Rc::<u32>::new_uninit();
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
    ///
    ///     five.assume_init()
    /// };
    ///
    /// assert_eq!(*five, 5)
    /// ```
    ///
    ///
    #[unstable(feature = "new_uninit", issue = "63291")]
    #[inline]
    pub unsafe fn assume_init(self) -> Rc<T> {
        Rc::from_inner(mem::ManuallyDrop::new(self).ptr.cast())
    }
}

impl<T> Rc<[mem::MaybeUninit<T>]> {
    /// 转换为 `Rc<[T]>`。
    ///
    /// # Safety
    ///
    /// 与 [`MaybeUninit::assume_init`] 一样，由调用方负责确保内部值确实处于初始化状态。
    ///
    /// 在内容尚未完全初始化时调用此方法会立即导致未定义的行为。
    ///
    /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut values = Rc::<[u32]>::new_uninit_slice(3);
    ///
    /// let values = unsafe {
    ///     // 延迟初始化:
    ///     Rc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
    ///     Rc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
    ///     Rc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
    ///
    ///     values.assume_init()
    /// };
    ///
    /// assert_eq!(*values, [1, 2, 3])
    /// ```
    ///
    ///
    #[unstable(feature = "new_uninit", issue = "63291")]
    #[inline]
    pub unsafe fn assume_init(self) -> Rc<[T]> {
        unsafe { Rc::from_ptr(mem::ManuallyDrop::new(self).ptr.as_ptr() as _) }
    }
}

impl<T: ?Sized> Rc<T> {
    /// 消耗 `Rc`，返回包装的指针。
    ///
    /// 为避免内存泄漏，必须使用 [`Rc::from_raw`][from_raw] 将指针转换回 `Rc`。
    ///
    ///
    /// [from_raw]: Rc::from_raw
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let x = Rc::new("hello".to_owned());
    /// let x_ptr = Rc::into_raw(x);
    /// assert_eq!(unsafe { &*x_ptr }, "hello");
    /// ```
    #[stable(feature = "rc_raw", since = "1.17.0")]
    pub fn into_raw(this: Self) -> *const T {
        let ptr = Self::as_ptr(&this);
        mem::forget(this);
        ptr
    }

    /// 为数据提供裸指针。
    ///
    /// 计数不会受到任何影响，并且不会消耗 `Rc`。
    /// 只要 `Rc` 中存在大量计数，指针就有效。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let x = Rc::new("hello".to_owned());
    /// let y = Rc::clone(&x);
    /// let x_ptr = Rc::as_ptr(&x);
    /// assert_eq!(x_ptr, Rc::as_ptr(&y));
    /// assert_eq!(unsafe { &*x_ptr }, "hello");
    /// ```
    #[stable(feature = "weak_into_raw", since = "1.45.0")]
    pub fn as_ptr(this: &Self) -> *const T {
        let ptr: *mut RcBox<T> = NonNull::as_ptr(this.ptr);

        // SAFETY: 这不能通过 Deref::deref 或 Rc::inner，因为这是保留 raw/mut 出处所必需的，例如
        // `get_mut` 通过 `from_raw` 恢复 Rc 后，可以通过指针写入。
        //
        unsafe { ptr::addr_of_mut!((*ptr).value) }
    }

    /// 从裸指针构造 `Rc<T>`。
    ///
    /// 裸指针必须事先由调用返回到 [`Rc<U>::into_raw`][into_raw]，其中 `U` 的大小和对齐方式必须与 `T` 相同。
    /// 如果 `U` 是 `T`，这是很简单的。
    /// 请注意，如果 `U` 不是 `T`，但是具有相同的大小和对齐方式，则基本上就像对不同类型的引用进行转换一样。
    /// 有关在这种情况下适用的限制的更多信息，请参见 [`mem::transmute`][transmute]。
    ///
    /// `from_raw` 的用户必须确保 `T` 的特定值仅被丢弃一次。
    ///
    /// 此函数不安全，因为使用不当可能会导致内存不安全，即使从未访问返回的 `Rc<T>` 也是如此。
    ///
    /// [into_raw]: Rc::into_raw
    /// [transmute]: core::mem::transmute
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let x = Rc::new("hello".to_owned());
    /// let x_ptr = Rc::into_raw(x);
    ///
    /// unsafe {
    ///     // 转换回 `Rc` 以防止泄漏。
    ///     let x = Rc::from_raw(x_ptr);
    ///     assert_eq!(&*x, "hello");
    ///
    ///     // 进一步调用 `Rc::from_raw(x_ptr)` 将导致内存不安全。
    /// }
    ///
    /// // 当 `x` 离开作用域时，内存被释放，所以 `x_ptr` 现在悬空了!
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rc_raw", since = "1.17.0")]
    pub unsafe fn from_raw(ptr: *const T) -> Self {
        let offset = unsafe { data_offset(ptr) };

        // 反转偏移量以找到原始的 RcBox。
        let rc_ptr =
            unsafe { (ptr as *mut RcBox<T>).set_ptr_value((ptr as *mut u8).offset(-offset)) };

        unsafe { Self::from_ptr(rc_ptr) }
    }

    /// 创建一个指向该分配的新 [`Weak`] 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// let weak_five = Rc::downgrade(&five);
    /// ```
    #[stable(feature = "rc_weak", since = "1.4.0")]
    pub fn downgrade(this: &Self) -> Weak<T> {
        this.inner().inc_weak();
        // 确保我们不会产生悬空的弱点
        debug_assert!(!is_dangling(this.ptr.as_ptr()));
        Weak { ptr: this.ptr }
    }

    /// 获取指向该分配的 [`Weak`] 指针的数量。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    /// let _weak_five = Rc::downgrade(&five);
    ///
    /// assert_eq!(1, Rc::weak_count(&five));
    /// ```
    #[inline]
    #[stable(feature = "rc_counts", since = "1.15.0")]
    pub fn weak_count(this: &Self) -> usize {
        this.inner().weak() - 1
    }

    /// 获取指向此分配的强 (`Rc`) 指针的数量。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    /// let _also_five = Rc::clone(&five);
    ///
    /// assert_eq!(2, Rc::strong_count(&five));
    /// ```
    #[inline]
    #[stable(feature = "rc_counts", since = "1.15.0")]
    pub fn strong_count(this: &Self) -> usize {
        this.inner().strong()
    }

    /// 将与提供的指针关联的 `Rc<T>` 上的强引用计数增加 1。
    ///
    /// # Safety
    ///
    /// 指针必须是通过 `Rc::into_raw` 获得的，并且关联的 `Rc` 实例必须是有效的 (即
    /// 在此方法的持续时间内，强引用计数必须至少为 1)。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// unsafe {
    ///     let ptr = Rc::into_raw(five);
    ///     Rc::increment_strong_count(ptr);
    ///
    ///     let five = Rc::from_raw(ptr);
    ///     assert_eq!(2, Rc::strong_count(&five));
    /// }
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rc_mutate_strong_count", since = "1.53.0")]
    pub unsafe fn increment_strong_count(ptr: *const T) {
        // 保留 Rc，但不要通过包装在手动丢弃中来触及引用计数
        let rc = unsafe { mem::ManuallyDrop::new(Rc::<T>::from_raw(ptr)) };
        // 现在增加 refcount，但也不要丢弃新的 refcount
        let _rc_clone: mem::ManuallyDrop<_> = rc.clone();
    }

    /// 将与提供的指针关联的 `Rc<T>` 上的强引用计数减一。
    ///
    /// # Safety
    ///
    /// 指针必须是通过 `Rc::into_raw` 获得的，并且关联的 `Rc` 实例必须是有效的 (即
    /// 调用此方法时，强引用计数必须至少为 1)。
    /// 此方法可用于释放最终的 `Rc` 和后备存储，但**不应**在最终的 `Rc` 释放后调用。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// unsafe {
    ///     let ptr = Rc::into_raw(five);
    ///     Rc::increment_strong_count(ptr);
    ///
    ///     let five = Rc::from_raw(ptr);
    ///     assert_eq!(2, Rc::strong_count(&five));
    ///     Rc::decrement_strong_count(ptr);
    ///     assert_eq!(1, Rc::strong_count(&five));
    /// }
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rc_mutate_strong_count", since = "1.53.0")]
    pub unsafe fn decrement_strong_count(ptr: *const T) {
        unsafe { mem::drop(Rc::from_raw(ptr)) };
    }

    /// 如果没有其他指向该分配的 `Rc` 或 [`Weak`] 指针，则返回 `true`。
    ///
    #[inline]
    fn is_unique(this: &Self) -> bool {
        Rc::weak_count(this) == 0 && Rc::strong_count(this) == 1
    }

    /// 如果没有其他 `Rc` 或 [`Weak`] 指向相同分配的指针，则返回给定 `Rc` 的可变引用。
    ///
    ///
    /// 否则返回 [`None`]，因为更改共享值并不安全。
    ///
    /// 另请参见 [`make_mut`][make_mut]，当存在其他指针时，它将 [`clone`][clone] 内部值。
    ///
    /// [make_mut]: Rc::make_mut
    /// [clone]: Clone::clone
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let mut x = Rc::new(3);
    /// *Rc::get_mut(&mut x).unwrap() = 4;
    /// assert_eq!(*x, 4);
    ///
    /// let _y = Rc::clone(&x);
    /// assert!(Rc::get_mut(&mut x).is_none());
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rc_unique", since = "1.4.0")]
    pub fn get_mut(this: &mut Self) -> Option<&mut T> {
        if Rc::is_unique(this) { unsafe { Some(Rc::get_mut_unchecked(this)) } } else { None }
    }

    /// 将变量引用返回给定的 `Rc`，而不进行任何检查。
    ///
    /// 另请参见 [`get_mut`]，它是安全的并且进行适当的检查。
    ///
    /// [`get_mut`]: Rc::get_mut
    ///
    /// # Safety
    ///
    /// 在返回的借用期间，不得解引用其他指向相同分配的 `Rc` 或 [`Weak`] 指针。
    ///
    /// 如果不存在这样的指针 (例如紧接在 `Rc::new` 之后)，则情况很简单。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::rc::Rc;
    ///
    /// let mut x = Rc::new(String::new());
    /// unsafe {
    ///     Rc::get_mut_unchecked(&mut x).push_str("foo")
    /// }
    /// assert_eq!(*x, "foo");
    /// ```
    ///
    ///
    #[inline]
    #[unstable(feature = "get_mut_unchecked", issue = "63292")]
    pub unsafe fn get_mut_unchecked(this: &mut Self) -> &mut T {
        // 我们小心 *不要* 创建覆盖 "count" 字段的引用，因为这会与对引用计数的访问产生冲突 (例如
        // 由 `Weak`)。
        unsafe { &mut (*this.ptr.as_ptr()).value }
    }

    #[inline]
    #[stable(feature = "ptr_eq", since = "1.17.0")]
    /// 如果两个 Rc 指向相同的分配 (类似于 [`ptr::eq`])，则返回 `true`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    /// let same_five = Rc::clone(&five);
    /// let other_five = Rc::new(5);
    ///
    /// assert!(Rc::ptr_eq(&five, &same_five));
    /// assert!(!Rc::ptr_eq(&five, &other_five));
    /// ```
    ///
    /// [`ptr::eq`]: core::ptr::eq
    pub fn ptr_eq(this: &Self, other: &Self) -> bool {
        this.ptr.as_ptr() == other.ptr.as_ptr()
    }
}

impl<T: Clone> Rc<T> {
    /// 对给定的 `Rc` 进行可变引用。
    ///
    /// 如果还有其他指向同一分配的 `Rc` 指针，则 `make_mut` 会将 [`clone`] 的内部值分配给新分配，以确保唯一的所有权。
    /// 这也称为写时克隆。
    ///
    /// 如果没有其他指向该分配的 `Rc` 指针，则指向该分配的 [`Weak`] 指针将被取消关联。
    ///
    /// 另请参见 [`get_mut`]，它将失败而不是克隆。
    ///
    /// [`clone`]: Clone::clone
    /// [`get_mut`]: Rc::get_mut
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let mut data = Rc::new(5);
    ///
    /// *Rc::make_mut(&mut data) += 1;        // 不会克隆任何东西
    /// let mut other_data = Rc::clone(&data);    // 不会克隆内部数据
    /// *Rc::make_mut(&mut data) += 1;        // 克隆内部数据
    /// *Rc::make_mut(&mut data) += 1;        // 不会克隆任何东西
    /// *Rc::make_mut(&mut other_data) *= 2;  // 不会克隆任何东西
    ///
    /// // 现在，`data` 和 `other_data` 指向不同的分配。
    /// assert_eq!(*data, 8);
    /// assert_eq!(*other_data, 12);
    /// ```
    ///
    /// [`Weak`] 指针将被取消关联:
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let mut data = Rc::new(75);
    /// let weak = Rc::downgrade(&data);
    ///
    /// assert!(75 == *data);
    /// assert!(75 == *weak.upgrade().unwrap());
    ///
    /// *Rc::make_mut(&mut data) += 1;
    ///
    /// assert!(76 == *data);
    /// assert!(weak.upgrade().is_none());
    /// ```
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "rc_unique", since = "1.4.0")]
    pub fn make_mut(this: &mut Self) -> &mut T {
        if Rc::strong_count(this) != 1 {
            // 要克隆数据，还有其他 Rcs。
            // 预分配内存以允许直接写入克隆的值。
            let mut rc = Self::new_uninit();
            unsafe {
                let data = Rc::get_mut_unchecked(&mut rc);
                (**this).write_clone_into_raw(data.as_mut_ptr());
                *this = rc.assume_init();
            }
        } else if Rc::weak_count(this) != 0 {
            // 只能窃取数据，剩下的就是弱点
            let mut rc = Self::new_uninit();
            unsafe {
                let data = Rc::get_mut_unchecked(&mut rc);
                data.as_mut_ptr().copy_from_nonoverlapping(&**this, 1);

                this.inner().dec_strong();
                // 删除隐式的强弱引用 (无需在此处制作假的弱项 - 我们知道其他弱项也可以为我们清除)
                //
                this.inner().dec_weak();
                ptr::write(this, rc.assume_init());
            }
        }
        // 这种不安全性是可以的，因为我们保证返回的指针是将永远返回到 T 的 *only* 指针。
        // 此时我们的引用计数保证为 1，并且我们要求 `Rc<T>` 本身为 `mut`，因此我们将唯一可能的引用返回给分配。
        //
        //
        //
        unsafe { &mut this.ptr.as_mut().value }
    }
}

impl Rc<dyn Any> {
    #[inline]
    #[stable(feature = "rc_downcast", since = "1.29.0")]
    /// 尝试将 `Rc<dyn Any>` 转换为具体类型。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::any::Any;
    /// use std::rc::Rc;
    ///
    /// fn print_if_string(value: Rc<dyn Any>) {
    ///     if let Ok(string) = value.downcast::<String>() {
    ///         println!("String ({}): {}", string.len(), string);
    ///     }
    /// }
    ///
    /// let my_string = "Hello World".to_string();
    /// print_if_string(Rc::new(my_string));
    /// print_if_string(Rc::new(0i8));
    /// ```
    pub fn downcast<T: Any>(self) -> Result<Rc<T>, Rc<dyn Any>> {
        if (*self).is::<T>() {
            let ptr = self.ptr.cast::<RcBox<T>>();
            forget(self);
            Ok(Rc::from_inner(ptr))
        } else {
            Err(self)
        }
    }
}

impl<T: ?Sized> Rc<T> {
    /// 为 `RcBox<T>` 分配足够的空间，以容纳可能未定义大小的内部值，其中该值具有提供的布局。
    ///
    /// 函数 `mem_to_rcbox` 用数据指针调用，并且必须返回 `RcBox<T>` 的 (可能是胖的) 指针。
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    unsafe fn allocate_for_layout(
        value_layout: Layout,
        allocate: impl FnOnce(Layout) -> Result<NonNull<[u8]>, AllocError>,
        mem_to_rcbox: impl FnOnce(*mut u8) -> *mut RcBox<T>,
    ) -> *mut RcBox<T> {
        // 使用给定的值布局计算布局。
        // 以前，在表达式 `&*(ptr as* const RcBox<T>)` 上计算布局，但是这会产生未对齐的引用 (请参见 #54908)。
        //
        //
        let layout = Layout::new::<RcBox<()>>().extend(value_layout).unwrap().0.pad_to_align();
        unsafe {
            Rc::try_allocate_for_layout(value_layout, allocate, mem_to_rcbox)
                .unwrap_or_else(|_| handle_alloc_error(layout))
        }
    }

    /// 为 `RcBox<T>` 分配足够的空间，以容纳可能未定义大小的内部值 (该值具有提供的布局)，如果分配失败，则返回错误。
    ///
    ///
    /// 函数 `mem_to_rcbox` 用数据指针调用，并且必须返回 `RcBox<T>` 的 (可能是胖的) 指针。
    ///
    ///
    #[inline]
    unsafe fn try_allocate_for_layout(
        value_layout: Layout,
        allocate: impl FnOnce(Layout) -> Result<NonNull<[u8]>, AllocError>,
        mem_to_rcbox: impl FnOnce(*mut u8) -> *mut RcBox<T>,
    ) -> Result<*mut RcBox<T>, AllocError> {
        // 使用给定的值布局计算布局。
        // 以前，在表达式 `&*(ptr as* const RcBox<T>)` 上计算布局，但是这会产生未对齐的引用 (请参见 #54908)。
        //
        //
        let layout = Layout::new::<RcBox<()>>().extend(value_layout).unwrap().0.pad_to_align();

        // 为布局分配。
        let ptr = allocate(layout)?;

        // 初始化 RcBox
        let inner = mem_to_rcbox(ptr.as_non_null_ptr().as_ptr());
        unsafe {
            debug_assert_eq!(Layout::for_value(&*inner), layout);

            ptr::write(&mut (*inner).strong, Cell::new(1));
            ptr::write(&mut (*inner).weak, Cell::new(1));
        }

        Ok(inner)
    }

    /// 为 `RcBox` 分配足够的空间，以容纳未定义大小的内部值
    #[cfg(not(no_global_oom_handling))]
    unsafe fn allocate_for_ptr(ptr: *const T) -> *mut RcBox<T> {
        // 使用给定的值分配 `RcBox<T>`。
        unsafe {
            Self::allocate_for_layout(
                Layout::for_value(&*ptr),
                |layout| Global.allocate(layout),
                |mem| (ptr as *mut RcBox<T>).set_ptr_value(mem),
            )
        }
    }

    #[cfg(not(no_global_oom_handling))]
    fn from_box(v: Box<T>) -> Rc<T> {
        unsafe {
            let (box_unique, alloc) = Box::into_unique(v);
            let bptr = box_unique.as_ptr();

            let value_size = size_of_val(&*bptr);
            let ptr = Self::allocate_for_ptr(bptr);

            // 将值复制为字节
            ptr::copy_nonoverlapping(
                bptr as *const T as *const u8,
                &mut (*ptr).value as *mut _ as *mut u8,
                value_size,
            );

            // 释放分配而不丢弃其内容
            box_free(box_unique, alloc);

            Self::from_ptr(ptr)
        }
    }
}

impl<T> Rc<[T]> {
    /// 用给定的长度分配 `RcBox<[T]>`。
    #[cfg(not(no_global_oom_handling))]
    unsafe fn allocate_for_slice(len: usize) -> *mut RcBox<[T]> {
        unsafe {
            Self::allocate_for_layout(
                Layout::array::<T>(len).unwrap(),
                |layout| Global.allocate(layout),
                |mem| ptr::slice_from_raw_parts_mut(mem as *mut T, len) as *mut RcBox<[T]>,
            )
        }
    }

    /// 将切片中的元素复制到新分配的 Rc<\[T\]> 中
    ///
    /// 不安全，因为调用者必须拥有所有权或绑定 `T: Copy`
    #[cfg(not(no_global_oom_handling))]
    unsafe fn copy_from_slice(v: &[T]) -> Rc<[T]> {
        unsafe {
            let ptr = Self::allocate_for_slice(v.len());
            ptr::copy_nonoverlapping(v.as_ptr(), &mut (*ptr).value as *mut [T] as *mut T, v.len());
            Self::from_ptr(ptr)
        }
    }

    /// 从已知为一定大小的迭代器构造 `Rc<[T]>`。
    ///
    /// 如果大小错误，行为是不确定的。
    #[cfg(not(no_global_oom_handling))]
    unsafe fn from_iter_exact(iter: impl iter::Iterator<Item = T>, len: usize) -> Rc<[T]> {
        // Panic 在克隆 T 元素时进行保护。
        // 如果出现 panic，将丢弃已写入新 RcBox 的元素，然后释放内存。
        //
        struct Guard<T> {
            mem: NonNull<u8>,
            elems: *mut T,
            layout: Layout,
            n_elems: usize,
        }

        impl<T> Drop for Guard<T> {
            fn drop(&mut self) {
                unsafe {
                    let slice = from_raw_parts_mut(self.elems, self.n_elems);
                    ptr::drop_in_place(slice);

                    Global.deallocate(self.mem, self.layout);
                }
            }
        }

        unsafe {
            let ptr = Self::allocate_for_slice(len);

            let mem = ptr as *mut _ as *mut u8;
            let layout = Layout::for_value(&*ptr);

            // 指向第一个元素的指针
            let elems = &mut (*ptr).value as *mut [T] as *mut T;

            let mut guard = Guard { mem: NonNull::new_unchecked(mem), elems, layout, n_elems: 0 };

            for (i, item) in iter.enumerate() {
                ptr::write(elems.add(i), item);
                guard.n_elems += 1;
            }

            // 全部清空。忘了守卫吧，这样就不会释放新的 RcBox。
            forget(guard);

            Self::from_ptr(ptr)
        }
    }
}

/// `From<&[T]>` 使用的专业化 trait。
trait RcFromSlice<T> {
    fn from_slice(slice: &[T]) -> Self;
}

#[cfg(not(no_global_oom_handling))]
impl<T: Clone> RcFromSlice<T> for Rc<[T]> {
    #[inline]
    default fn from_slice(v: &[T]) -> Self {
        unsafe { Self::from_iter_exact(v.iter().cloned(), v.len()) }
    }
}

#[cfg(not(no_global_oom_handling))]
impl<T: Copy> RcFromSlice<T> for Rc<[T]> {
    #[inline]
    fn from_slice(v: &[T]) -> Self {
        unsafe { Rc::copy_from_slice(v) }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Deref for Rc<T> {
    type Target = T;

    #[inline(always)]
    fn deref(&self) -> &T {
        &self.inner().value
    }
}

#[unstable(feature = "receiver_trait", issue = "none")]
impl<T: ?Sized> Receiver for Rc<T> {}

#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<#[may_dangle] T: ?Sized> Drop for Rc<T> {
    /// 丢弃 `Rc`。
    ///
    /// 这将减少强引用计数。
    /// 如果强引用计数达到零，那么唯一的其他引用 (如果有) 是 [`Weak`]，因此我们将 `drop` 作为内部值。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// struct Foo;
    ///
    /// impl Drop for Foo {
    ///     fn drop(&mut self) {
    ///         println!("dropped!");
    ///     }
    /// }
    ///
    /// let foo  = Rc::new(Foo);
    /// let foo2 = Rc::clone(&foo);
    ///
    /// drop(foo);    // 不打印任何东西
    /// drop(foo2);   // 打印 "dropped!"
    /// ```
    fn drop(&mut self) {
        unsafe {
            self.inner().dec_strong();
            if self.inner().strong() == 0 {
                // 销毁所包含的对象
                ptr::drop_in_place(Self::get_mut_unchecked(self));

                // 现在我们已经销毁了内容，请删除隐式 "strong weak" 指针。
                //
                self.inner().dec_weak();

                if self.inner().weak() == 0 {
                    Global.deallocate(self.ptr.cast(), Layout::for_value(self.ptr.as_ref()));
                }
            }
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Clone for Rc<T> {
    /// 克隆 `Rc` 指针。
    ///
    /// 这将创建另一个指向相同分配的指针，从而增加了强引用计数。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// let _ = Rc::clone(&five);
    /// ```
    #[inline]
    fn clone(&self) -> Rc<T> {
        self.inner().inc_strong();
        Self::from_inner(self.ptr)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Default> Default for Rc<T> {
    /// 用 `T` 的 `Default` 值创建一个新的 `Rc<T>`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let x: Rc<i32> = Default::default();
    /// assert_eq!(*x, 0);
    /// ```
    #[inline]
    fn default() -> Rc<T> {
        Rc::new(Default::default())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
trait RcEqIdent<T: ?Sized + PartialEq> {
    fn eq(&self, other: &Rc<T>) -> bool;
    fn ne(&self, other: &Rc<T>) -> bool;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + PartialEq> RcEqIdent<T> for Rc<T> {
    #[inline]
    default fn eq(&self, other: &Rc<T>) -> bool {
        **self == **other
    }

    #[inline]
    default fn ne(&self, other: &Rc<T>) -> bool {
        **self != **other
    }
}

// 即使 `Eq` 有一种方法，也可以允许专门研究 `Eq`。
#[rustc_unsafe_specialization_marker]
pub(crate) trait MarkerEq: PartialEq<Self> {}

impl<T: Eq> MarkerEq for T {}

/// 我们在这里进行这种专门化，而不是对 `&T` 进行更一般的优化，因为否则会增加对引用的所有相等性检查的成本。
/// 我们假设 `Rc`s 用于存储较大的值，这些值克隆起来较慢，但在检查相等性时又很繁琐，从而使此成本更容易得到回报。
///
/// 与两个 `&T` 相比，它更有可能具有两个指向相同值的 `Rc` 克隆。
///
/// 仅当 `T: Eq` 作为 `PartialEq` 故意不自反时，我们才能执行此操作。
///
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + MarkerEq> RcEqIdent<T> for Rc<T> {
    #[inline]
    fn eq(&self, other: &Rc<T>) -> bool {
        Rc::ptr_eq(self, other) || **self == **other
    }

    #[inline]
    fn ne(&self, other: &Rc<T>) -> bool {
        !Rc::ptr_eq(self, other) && **self != **other
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + PartialEq> PartialEq for Rc<T> {
    /// 两个 Rc 相等。
    ///
    /// 即使两个 `Rc` 的内部值相等，即使它们存储在不同的分配中，它们也相等。
    ///
    /// 如果 `T` 还实现了 `Eq` (暗示相等的自反性)，则指向同一分配的两个 `Rc' 始终相等。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five == Rc::new(5));
    /// ```
    ///
    ///
    #[inline]
    fn eq(&self, other: &Rc<T>) -> bool {
        RcEqIdent::eq(self, other)
    }

    /// 两个 `Rc` 的不等式。
    ///
    /// 如果两个 `Rc` 的内部值不相等，则它们是不相等的。
    ///
    /// 如果 `T` 还实现了 `Eq` (暗示相等性的反射性)，则指向同一分配的两个 Rc 永远不会相等。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five != Rc::new(6));
    /// ```
    ///
    #[inline]
    fn ne(&self, other: &Rc<T>) -> bool {
        RcEqIdent::ne(self, other)
    }
}

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

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + PartialOrd> PartialOrd for Rc<T> {
    /// 两个 `Rc` 的部分比较。
    ///
    /// 通过调用 `partial_cmp()` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    /// use std::cmp::Ordering;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6)));
    /// ```
    #[inline(always)]
    fn partial_cmp(&self, other: &Rc<T>) -> Option<Ordering> {
        (**self).partial_cmp(&**other)
    }

    /// 小于两个 Rc 的比较。
    ///
    /// 通过调用 `<` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five < Rc::new(6));
    /// ```
    #[inline(always)]
    fn lt(&self, other: &Rc<T>) -> bool {
        **self < **other
    }

    /// 两个 `Rc` 的小于或等于比较。
    ///
    /// 通过调用 `<=` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five <= Rc::new(5));
    /// ```
    #[inline(always)]
    fn le(&self, other: &Rc<T>) -> bool {
        **self <= **other
    }

    /// 大于两个 Rc 的比较。
    ///
    /// 通过调用 `>` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five > Rc::new(4));
    /// ```
    #[inline(always)]
    fn gt(&self, other: &Rc<T>) -> bool {
        **self > **other
    }

    /// 两个 `Rc` 的大于或等于比较。
    ///
    /// 通过调用 `>=` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert!(five >= Rc::new(5));
    /// ```
    #[inline(always)]
    fn ge(&self, other: &Rc<T>) -> bool {
        **self >= **other
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + Ord> Ord for Rc<T> {
    /// 两个 `Rc` 的比较。
    ///
    /// 通过调用 `cmp()` 的内部值来比较两者。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    /// use std::cmp::Ordering;
    ///
    /// let five = Rc::new(5);
    ///
    /// assert_eq!(Ordering::Less, five.cmp(&Rc::new(6)));
    /// ```
    #[inline]
    fn cmp(&self, other: &Rc<T>) -> Ordering {
        (**self).cmp(&**other)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + Hash> Hash for Rc<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        (**self).hash(state);
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + fmt::Display> fmt::Display for Rc<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&**self, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + fmt::Debug> fmt::Debug for Rc<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&**self, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> fmt::Pointer for Rc<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&(&**self as *const T), f)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "from_for_ptrs", since = "1.6.0")]
impl<T> From<T> for Rc<T> {
    /// 将泛型 `T` 转换为 `Rc<T>`
    ///
    /// 转换在堆上分配，并将 `t` 从栈移到堆中。
    ///
    /// # Example
    ///
    /// ```rust
    /// # use std::rc::Rc;
    /// let x = 5;
    /// let rc = Rc::new(5);
    ///
    /// assert_eq!(Rc::from(x), rc);
    /// ```
    fn from(t: T) -> Self {
        Rc::new(t)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T: Clone> From<&[T]> for Rc<[T]> {
    /// 分配一个引用计数的切片，并通过克隆 `v` 的项来填充它。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::rc::Rc;
    /// let original: &[i32] = &[1, 2, 3];
    /// let shared: Rc<[i32]> = Rc::from(original);
    /// assert_eq!(&[1, 2, 3], &shared[..]);
    /// ```
    #[inline]
    fn from(v: &[T]) -> Rc<[T]> {
        <Self as RcFromSlice<T>>::from_slice(v)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<&str> for Rc<str> {
    /// 分配一个引用计数的字符串切片并将 `v` 复制到其中。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::rc::Rc;
    /// let shared: Rc<str> = Rc::from("statue");
    /// assert_eq!("statue", &shared[..]);
    /// ```
    #[inline]
    fn from(v: &str) -> Rc<str> {
        let rc = Rc::<[u8]>::from(v.as_bytes());
        unsafe { Rc::from_raw(Rc::into_raw(rc) as *const str) }
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl From<String> for Rc<str> {
    /// 分配一个引用计数的字符串切片并将 `v` 复制到其中。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::rc::Rc;
    /// let original: String = "statue".to_owned();
    /// let shared: Rc<str> = Rc::from(original);
    /// assert_eq!("statue", &shared[..]);
    /// ```
    #[inline]
    fn from(v: String) -> Rc<str> {
        Rc::from(&v[..])
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T: ?Sized> From<Box<T>> for Rc<T> {
    /// 将 boxed 对象移动到引用计数的新分配。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::rc::Rc;
    /// let original: Box<i32> = Box::new(1);
    /// let shared: Rc<i32> = Rc::from(original);
    /// assert_eq!(1, *shared);
    /// ```
    #[inline]
    fn from(v: Box<T>) -> Rc<T> {
        Rc::from_box(v)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T> From<Vec<T>> for Rc<[T]> {
    /// 分配一个引用计数的切片，并将 `v` 的项移入其中。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::rc::Rc;
    /// let original: Box<Vec<i32>> = Box::new(vec![1, 2, 3]);
    /// let shared: Rc<Vec<i32>> = Rc::from(original);
    /// assert_eq!(vec![1, 2, 3], *shared);
    /// ```
    #[inline]
    fn from(mut v: Vec<T>) -> Rc<[T]> {
        unsafe {
            let rc = Rc::copy_from_slice(&v);

            // 允许 Vec 释放其内存，但不销毁其内容
            v.set_len(0);

            rc
        }
    }
}

#[stable(feature = "shared_from_cow", since = "1.45.0")]
impl<'a, B> From<Cow<'a, B>> for Rc<B>
where
    B: ToOwned + ?Sized,
    Rc<B>: From<&'a B> + From<B::Owned>,
{
    /// 通过复制其内容，从写时克隆指针创建一个引用计数指针。
    ///
    ///
    /// # Example
    ///
    /// ```rust
    /// # use std::rc::Rc;
    /// # use std::borrow::Cow;
    /// let cow: Cow<str> = Cow::Borrowed("eggplant");
    /// let shared: Rc<str> = Rc::from(cow);
    /// assert_eq!("eggplant", &shared[..]);
    /// ```
    #[inline]
    fn from(cow: Cow<'a, B>) -> Rc<B> {
        match cow {
            Cow::Borrowed(s) => Rc::from(s),
            Cow::Owned(s) => Rc::from(s),
        }
    }
}

#[stable(feature = "boxed_slice_try_from", since = "1.43.0")]
impl<T, const N: usize> TryFrom<Rc<[T]>> for Rc<[T; N]> {
    type Error = Rc<[T]>;

    fn try_from(boxed_slice: Rc<[T]>) -> Result<Self, Self::Error> {
        if boxed_slice.len() == N {
            Ok(unsafe { Rc::from_raw(Rc::into_raw(boxed_slice) as *mut [T; N]) })
        } else {
            Err(boxed_slice)
        }
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_iter", since = "1.37.0")]
impl<T> iter::FromIterator<T> for Rc<[T]> {
    /// 获取 `Iterator` 中的每个元素，并将其收集到 `Rc<[T]>` 中。
    ///
    /// # 性能特点
    ///
    /// ## 一般情况
    ///
    /// 在一般情况下，首先要收集到 `Vec<T>` 中来收集到 `Rc<[T]>` 中。也就是说，编写以下内容时:
    ///
    /// ```rust
    /// # use std::rc::Rc;
    /// let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();
    /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]);
    /// ```
    ///
    /// 这就像我们写的那样:
    ///
    /// ```rust
    /// # use std::rc::Rc;
    /// let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
    ///     .collect::<Vec<_>>() // 第一组分配在此处发生。
    ///     .into(); // `Rc<[T]>` 的第二个分配在此处进行。
    /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]);
    /// ```
    ///
    /// 这将分配构造 `Vec<T>` 所需的次数，然后分配一次，以将 `Vec<T>` 转换为 `Rc<[T]>`。
    ///
    ///
    /// ## 已知长度的迭代器
    ///
    /// 当您的 `Iterator` 实现 `TrustedLen` 且大小正确时，将为 `Rc<[T]>` 进行一次分配。例如:
    ///
    /// ```rust
    /// # use std::rc::Rc;
    /// let evens: Rc<[u8]> = (0..10).collect(); // 这里只进行一次分配。
    /// # assert_eq!(&*evens, &*(0..10).collect::<Vec<_>>());
    /// ```
    ///
    ///
    fn from_iter<I: iter::IntoIterator<Item = T>>(iter: I) -> Self {
        ToRcSlice::to_rc_slice(iter.into_iter())
    }
}

/// 专门的 trait 用于收集到 `Rc<[T]>` 中。
#[cfg(not(no_global_oom_handling))]
trait ToRcSlice<T>: Iterator<Item = T> + Sized {
    fn to_rc_slice(self) -> Rc<[T]>;
}

#[cfg(not(no_global_oom_handling))]
impl<T, I: Iterator<Item = T>> ToRcSlice<T> for I {
    default fn to_rc_slice(self) -> Rc<[T]> {
        self.collect::<Vec<T>>().into()
    }
}

#[cfg(not(no_global_oom_handling))]
impl<T, I: iter::TrustedLen<Item = T>> ToRcSlice<T> for I {
    fn to_rc_slice(self) -> Rc<[T]> {
        // `TrustedLen` 迭代器就是这种情况。
        let (low, high) = self.size_hint();
        if let Some(high) = high {
            debug_assert_eq!(
                low,
                high,
                "TrustedLen iterator's size hint is not exact: {:?}",
                (low, high)
            );

            unsafe {
                // SAFETY: 我们需要确保迭代器具有正确的长度并且我们有。
                Rc::from_iter_exact(self, low)
            }
        } else {
            // TrustedLen 契约保证 `upper_bound == `None` 意味着迭代器长度超过 `usize::MAX`。
            //
            // 默认实现将收集到一个 vec 中，这将是 panic。
            // 因此，我们立即在此处 panic 而不调用 `Vec` 代码。
            panic!("capacity overflow");
        }
    }
}

/// `Weak` 是 [`Rc`] 的版本，该版本对托管分配具有非所有权引用。通过调用 `Weak` 指针上的 [`upgrade`] 来访问该分配，该指针返回 [`Option`]`<`[`Rc`]`<T>>`。
///
/// 由于 `Weak` 引用不计入所有权，因此它不会防止存储在分配中的值被丢弃，并且 `Weak` 本身不保证该值仍然存在。
/// 因此，当 [`upgrade`] 时，它可能返回 [`None`]。
/// 但是请注意，`Weak` 引用 *确实* 会阻止分配本身 (后备存储) 被释放。
///
/// `Weak` 指针可用于保持对 [`Rc`] 管理的分配的临时引用，而又不会阻止其内部值被丢弃。
/// 它也用于防止 [`Rc`] 指针之间的循环引用，因为相互拥有引用将永远不允许丢弃 [`Rc`]。
/// 例如，一棵树可以具有从父节点到子节点的强 [`Rc`] 指针，以及从子节点到其父节点的 `Weak` 指针。
///
/// 获取 `Weak` 指针的典型方法是调用 [`Rc::downgrade`]。
///
/// [`upgrade`]: Weak::upgrade
///
///
///
///
///
///
///
#[stable(feature = "rc_weak", since = "1.4.0")]
pub struct Weak<T: ?Sized> {
    // 这是一个 `NonNull`，允许在枚举中优化此类型的大小，但它不一定是有效的指针。
    //
    // `Weak::new` 将此设置为 `usize::MAX`，以便不需要在堆上分配空间。
    // 这不是真正的指针所具有的值，因为 RcBox 的对齐方式至少为 2。
    // 仅当 `T: Sized` 时才有可能。未定义大小的 `T` 永远不会悬垂。
    //
    ptr: NonNull<RcBox<T>>,
}

#[stable(feature = "rc_weak", since = "1.4.0")]
impl<T: ?Sized> !marker::Send for Weak<T> {}
#[stable(feature = "rc_weak", since = "1.4.0")]
impl<T: ?Sized> !marker::Sync for Weak<T> {}

#[unstable(feature = "coerce_unsized", issue = "27732")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Weak<U>> for Weak<T> {}

#[unstable(feature = "dispatch_from_dyn", issue = "none")]
impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Weak<U>> for Weak<T> {}

impl<T> Weak<T> {
    /// 创建一个新的 `Weak<T>`，而不分配任何内存。
    /// 在返回值上调用 [`upgrade`] 总是得到 [`None`]。
    ///
    /// [`upgrade`]: Weak::upgrade
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Weak;
    ///
    /// let empty: Weak<i64> = Weak::new();
    /// assert!(empty.upgrade().is_none());
    /// ```
    #[stable(feature = "downgraded_weak", since = "1.10.0")]
    pub fn new() -> Weak<T> {
        Weak { ptr: NonNull::new(usize::MAX as *mut RcBox<T>).expect("MAX is not 0") }
    }
}

pub(crate) fn is_dangling<T: ?Sized>(ptr: *mut T) -> bool {
    let address = ptr as *mut () as usize;
    address == usize::MAX
}

/// 帮助程序类型，允许访问引用计数而无需对数据字段进行任何声明。
///
struct WeakInner<'a> {
    weak: &'a Cell<usize>,
    strong: &'a Cell<usize>,
}

impl<T: ?Sized> Weak<T> {
    /// 返回对此 `Weak<T>` 指向的对象 `T` 的裸指针。
    ///
    /// 该指针仅在有一些强引用时才有效。
    /// 指针可能悬空，未对齐，或者甚至 [`null`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    /// use std::ptr;
    ///
    /// let strong = Rc::new("hello".to_owned());
    /// let weak = Rc::downgrade(&strong);
    /// // 两者都指向同一个对象
    /// assert!(ptr::eq(&*strong, weak.as_ptr()));
    /// // 这里的强项使它保持活动状态，因此我们仍然可以访问该对象。
    /// assert_eq!("hello", unsafe { &*weak.as_ptr() });
    ///
    /// drop(strong);
    /// // 但是没有更多了。
    /// // 我们可以执行 weak.as_ptr()，但是访问指针将导致未定义的行为。
    /// // assert_eq!("hello", unsafe { &*weak.as_ptr() });
    /// ```
    ///
    /// [`null`]: core::ptr::null
    #[stable(feature = "rc_as_ptr", since = "1.45.0")]
    pub fn as_ptr(&self) -> *const T {
        let ptr: *mut RcBox<T> = NonNull::as_ptr(self.ptr);

        if is_dangling(ptr) {
            // 如果指针悬空，我们将直接返回哨兵。
            // 这不能是有效的有效负载地址，因为有效负载至少与 RcBox (usize) 对齐。
            ptr as *const T
        } else {
            // SAFETY: 如果 is_dangling 返回 false，则该指针是可解引用的。
            // 有效载荷可以在此时被丢弃，所以我们必须持有 provenance，因此请使用裸指针操作。
            //
            unsafe { ptr::addr_of_mut!((*ptr).value) }
        }
    }

    /// 消耗 `Weak<T>` 并将其转换为裸指针。
    ///
    /// 这会将弱指针转换为裸指针，同时仍保留一个弱引用的所有权 (此操作不会修改弱引用计数)。
    /// 可以将其转换回带有 [`from_raw`] 的 `Weak<T>`。
    ///
    /// 与 [`as_ptr`] 一样，访问指针目标的限制也适用。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::{Rc, Weak};
    ///
    /// let strong = Rc::new("hello".to_owned());
    /// let weak = Rc::downgrade(&strong);
    /// let raw = weak.into_raw();
    ///
    /// assert_eq!(1, Rc::weak_count(&strong));
    /// assert_eq!("hello", unsafe { &*raw });
    ///
    /// drop(unsafe { Weak::from_raw(raw) });
    /// assert_eq!(0, Rc::weak_count(&strong));
    /// ```
    ///
    /// [`from_raw`]: Weak::from_raw
    /// [`as_ptr`]: Weak::as_ptr
    ///
    ///
    #[stable(feature = "weak_into_raw", since = "1.45.0")]
    pub fn into_raw(self) -> *const T {
        let result = self.as_ptr();
        mem::forget(self);
        result
    }

    /// 将先前由 [`into_raw`] 创建的裸指针转换回 `Weak<T>`。
    ///
    /// 这可以用于安全地获得强引用 (稍后调用 [`upgrade`]) 或通过丢弃 `Weak<T>` 来分配弱引用计数。
    ///
    /// 它拥有一个弱引用的所有权 (由 [`new`] 创建的指针除外，因为它们不拥有任何东西; 该方法仍适用于它们)。
    ///
    /// # Safety
    ///
    /// 指针必须起源于 [`into_raw`]，并且仍然必须拥有其潜在的弱引用。
    ///
    /// 调用时允许强引用计数为 0。
    /// 不过，这需要当前表示为裸指针的弱引用的所有权 (该操作不会修改弱引用计数)，因此必须与 [`into_raw`] 的先前调用配对。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::{Rc, Weak};
    ///
    /// let strong = Rc::new("hello".to_owned());
    ///
    /// let raw_1 = Rc::downgrade(&strong).into_raw();
    /// let raw_2 = Rc::downgrade(&strong).into_raw();
    ///
    /// assert_eq!(2, Rc::weak_count(&strong));
    ///
    /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap());
    /// assert_eq!(1, Rc::weak_count(&strong));
    ///
    /// drop(strong);
    ///
    /// // 减少最后一个弱引用计数。
    /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());
    /// ```
    ///
    /// [`into_raw`]: Weak::into_raw
    /// [`upgrade`]: Weak::upgrade
    /// [`new`]: Weak::new
    ///
    ///
    ///
    ///
    #[stable(feature = "weak_into_raw", since = "1.45.0")]
    pub unsafe fn from_raw(ptr: *const T) -> Self {
        // 有关如何派生输入指针的上下文，请参见 Weak::as_ptr。

        let ptr = if is_dangling(ptr as *mut T) {
            // 这是悬空的弱点。
            ptr as *mut RcBox<T>
        } else {
            // 否则，我们保证指针来自无悬挂的弱。
            // SAFETY: data_offset 可以安全调用，因为 ptr 引用了一个真实的 (可能已丢弃) 的 T。
            let offset = unsafe { data_offset(ptr) };
            // 因此，我们反转偏移量以获得整个 RcBox。
            // SAFETY: 指针源自弱点，因此此偏移量是安全的。
            unsafe { (ptr as *mut RcBox<T>).set_ptr_value((ptr as *mut u8).offset(-offset)) }
        };

        // SAFETY: 我们现在已经恢复了原始的弱指针，因此可以创建弱指针。
        Weak { ptr: unsafe { NonNull::new_unchecked(ptr) } }
    }

    /// 尝试将 `Weak` 指针升级到 [`Rc`]，如果成功，则延迟丢弃内部值。
    ///
    ///
    /// 如果内部值已经被丢弃，则返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let five = Rc::new(5);
    ///
    /// let weak_five = Rc::downgrade(&five);
    ///
    /// let strong_five: Option<Rc<_>> = weak_five.upgrade();
    /// assert!(strong_five.is_some());
    ///
    /// // 销毁所有强指针。
    /// drop(strong_five);
    /// drop(five);
    ///
    /// assert!(weak_five.upgrade().is_none());
    /// ```
    #[stable(feature = "rc_weak", since = "1.4.0")]
    pub fn upgrade(&self) -> Option<Rc<T>> {
        let inner = self.inner()?;
        if inner.strong() == 0 {
            None
        } else {
            inner.inc_strong();
            Some(Rc::from_inner(self.ptr))
        }
    }

    /// 获取指向该分配的强 (`Rc`) 指针的数量。
    ///
    /// 如果 `self` 是使用 [`Weak::new`] 创建的，则将返回 0。
    #[stable(feature = "weak_counts", since = "1.41.0")]
    pub fn strong_count(&self) -> usize {
        if let Some(inner) = self.inner() { inner.strong() } else { 0 }
    }

    /// 获取指向该分配的 `Weak` 指针的数量。
    ///
    /// 如果没有剩余的强指针，它将返回零。
    #[stable(feature = "weak_counts", since = "1.41.0")]
    pub fn weak_count(&self) -> usize {
        self.inner()
            .map(|inner| {
                if inner.strong() > 0 {
                    inner.weak() - 1 // 减去隐含的弱指针
                } else {
                    0
                }
            })
            .unwrap_or(0)
    }

    /// 当指针悬空并且没有分配的 `RcBox` 时 (即，当 `Weak` 由 `Weak::new` 创建时)，返回 `None`。
    ///
    #[inline]
    fn inner(&self) -> Option<WeakInner<'_>> {
        if is_dangling(self.ptr.as_ptr()) {
            None
        } else {
            // 我们小心 *不要* 创建覆盖 "data" 字段的引用，因为该字段可能会同时被修改 (例如，如果最后一个 `Rc` 被丢弃，则数据字段将被原地丢弃)。
            //
            //
            Some(unsafe {
                let ptr = self.ptr.as_ptr();
                WeakInner { strong: &(*ptr).strong, weak: &(*ptr).weak }
            })
        }
    }

    /// 如果两个 `Weak' 指向相同的分配 (类似于 [`ptr::eq`])，或者两个都不指向任何分配 (因为它们是用 `Weak::new()` 创建的)，则返回 `true`。
    ///
    ///
    /// # Notes
    ///
    /// 由于这将比较指针，这意味着 `Weak::new()` 将彼此相等，即使它们不指向任何分配。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Rc;
    ///
    /// let first_rc = Rc::new(5);
    /// let first = Rc::downgrade(&first_rc);
    /// let second = Rc::downgrade(&first_rc);
    ///
    /// assert!(first.ptr_eq(&second));
    ///
    /// let third_rc = Rc::new(5);
    /// let third = Rc::downgrade(&third_rc);
    ///
    /// assert!(!first.ptr_eq(&third));
    /// ```
    ///
    /// 比较 `Weak::new`。
    ///
    /// ```
    /// use std::rc::{Rc, Weak};
    ///
    /// let first = Weak::new();
    /// let second = Weak::new();
    /// assert!(first.ptr_eq(&second));
    ///
    /// let third_rc = Rc::new(());
    /// let third = Rc::downgrade(&third_rc);
    /// assert!(!first.ptr_eq(&third));
    /// ```
    ///
    /// [`ptr::eq`]: core::ptr::eq
    ///
    ///
    #[inline]
    #[stable(feature = "weak_ptr_eq", since = "1.39.0")]
    pub fn ptr_eq(&self, other: &Self) -> bool {
        self.ptr.as_ptr() == other.ptr.as_ptr()
    }
}

#[stable(feature = "rc_weak", since = "1.4.0")]
unsafe impl<#[may_dangle] T: ?Sized> Drop for Weak<T> {
    /// 丢弃 `Weak` 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::{Rc, Weak};
    ///
    /// struct Foo;
    ///
    /// impl Drop for Foo {
    ///     fn drop(&mut self) {
    ///         println!("dropped!");
    ///     }
    /// }
    ///
    /// let foo = Rc::new(Foo);
    /// let weak_foo = Rc::downgrade(&foo);
    /// let other_weak_foo = Weak::clone(&weak_foo);
    ///
    /// drop(weak_foo);   // 不打印任何东西
    /// drop(foo);        // 打印 "dropped!"
    ///
    /// assert!(other_weak_foo.upgrade().is_none());
    /// ```
    fn drop(&mut self) {
        let inner = if let Some(inner) = self.inner() { inner } else { return };

        inner.dec_weak();
        // 弱引用计数从 1 开始，并且仅在所有强指针都消失后才变为零。
        //
        if inner.weak() == 0 {
            unsafe {
                Global.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr()));
            }
        }
    }
}

#[stable(feature = "rc_weak", since = "1.4.0")]
impl<T: ?Sized> Clone for Weak<T> {
    /// 克隆 `Weak` 指针，该指针指向相同的分配。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::{Rc, Weak};
    ///
    /// let weak_five = Rc::downgrade(&Rc::new(5));
    ///
    /// let _ = Weak::clone(&weak_five);
    /// ```
    #[inline]
    fn clone(&self) -> Weak<T> {
        if let Some(inner) = self.inner() {
            inner.inc_weak()
        }
        Weak { ptr: self.ptr }
    }
}

#[stable(feature = "rc_weak", since = "1.4.0")]
impl<T: ?Sized + fmt::Debug> fmt::Debug for Weak<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "(Weak)")
    }
}

#[stable(feature = "downgraded_weak", since = "1.10.0")]
impl<T> Default for Weak<T> {
    /// 创建一个新的 `Weak<T>`，而不分配任何内存。
    /// 在返回值上调用 [`upgrade`] 总是得到 [`None`]。
    ///
    /// [`None`]: Option
    /// [`upgrade`]: Weak::upgrade
    ///
    /// # Examples
    ///
    /// ```
    /// use std::rc::Weak;
    ///
    /// let empty: Weak<i64> = Default::default();
    /// assert!(empty.upgrade().is_none());
    /// ```
    fn default() -> Weak<T> {
        Weak::new()
    }
}

// NOTE: 我们在这里 check_add 来安全地处理 mem::forget。
// 特别是如果您使用 mem::forget Rcs (或 Weaks)，则引用计数可能会溢出，然后您可以在存在出色的 Rcs (或 Weaks) 的情况下释放分配。
//
// 我们终止是因为这是一个简陋的场景，我们不在乎会发生什么 - 真正的程序都不会遇到这种情况。
//
// 这应该具有可忽略的开销，因为由于所有权和移动语义，您实际上不需要在 Rust 中克隆太多代码。
//
//

#[doc(hidden)]
trait RcInnerPtr {
    fn weak_ref(&self) -> &Cell<usize>;
    fn strong_ref(&self) -> &Cell<usize>;

    #[inline]
    fn strong(&self) -> usize {
        self.strong_ref().get()
    }

    #[inline]
    fn inc_strong(&self) {
        let strong = self.strong();

        // 我们要终止溢出而不是丢弃该值。
        // 调用时，引用计数永远不会为零;
        // 但是，我们在此处插入一个终止以向 LLVM 提示进行其他优化时所错过的优化。
        //
        if strong == 0 || strong == usize::MAX {
            abort();
        }
        self.strong_ref().set(strong + 1);
    }

    #[inline]
    fn dec_strong(&self) {
        self.strong_ref().set(self.strong() - 1);
    }

    #[inline]
    fn weak(&self) -> usize {
        self.weak_ref().get()
    }

    #[inline]
    fn inc_weak(&self) {
        let weak = self.weak();

        // 我们要终止溢出而不是丢弃该值。
        // 调用时，引用计数永远不会为零;
        // 但是，我们在此处插入一个终止以向 LLVM 提示进行其他优化时所错过的优化。
        //
        if weak == 0 || weak == usize::MAX {
            abort();
        }
        self.weak_ref().set(weak + 1);
    }

    #[inline]
    fn dec_weak(&self) {
        self.weak_ref().set(self.weak() - 1);
    }
}

impl<T: ?Sized> RcInnerPtr for RcBox<T> {
    #[inline(always)]
    fn weak_ref(&self) -> &Cell<usize> {
        &self.weak
    }

    #[inline(always)]
    fn strong_ref(&self) -> &Cell<usize> {
        &self.strong
    }
}

impl<'a> RcInnerPtr for WeakInner<'a> {
    #[inline(always)]
    fn weak_ref(&self) -> &Cell<usize> {
        self.weak
    }

    #[inline(always)]
    fn strong_ref(&self) -> &Cell<usize> {
        self.strong
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> borrow::Borrow<T> for Rc<T> {
    fn borrow(&self) -> &T {
        &**self
    }
}

#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")]
impl<T: ?Sized> AsRef<T> for Rc<T> {
    fn as_ref(&self) -> &T {
        &**self
    }
}

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

/// 获取 `RcBox` 内指针后面的有效载荷的偏移量。
///
/// # Safety
///
/// 指针必须指向 T 的先前有效实例 (并具有有效的元数据)，但是允许丢弃 T。
///
unsafe fn data_offset<T: ?Sized>(ptr: *const T) -> isize {
    // 将未定义大小的值与 RcBox 的末端对齐。
    // 由于 RcBox 是 repr(C)，因此它将始终是内存中的最后一个字段。
    // SAFETY: 由于唯一可能的未定义大小类型是切片，trait 对象和外部类型，因此当前输入的安全要求足以满足 align_of_val_raw 的要求; 这是 std 之外可能不依赖的语言的实现细节。
    //
    //
    //
    unsafe { data_offset_align(align_of_val_raw(ptr)) }
}

#[inline]
fn data_offset_align(align: usize) -> isize {
    let layout = Layout::new::<RcBox<()>>();
    (layout.size() + layout.padding_needed_for(align)) as isize
}