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

//! 线程安全的引用计数指针。
//!
//! 有关更多详细信息，请参见 [`Arc<T>`][Arc] 文档。
//!
//! **Note**: 该模块仅在支持原子加载和指针存储的平台上可用。
//! 这可以在编译时使用 `#[cfg(target_has_atomic = "ptr")]` 检测到。
//!

use core::any::Any;
use core::borrow;
use core::cmp::Ordering;
use core::fmt;
use core::hash::{Hash, Hasher};
use core::hint;
use core::intrinsics::abort;
#[cfg(not(no_global_oom_handling))]
use core::iter;
use core::marker::{PhantomData, Unsize};
#[cfg(not(no_global_oom_handling))]
use core::mem::size_of_val;
use core::mem::{self, align_of_val_raw};
use core::ops::{CoerceUnsized, Deref, DispatchFromDyn, Receiver};
use core::panic::{RefUnwindSafe, UnwindSafe};
use core::pin::Pin;
use core::ptr::{self, NonNull};
#[cfg(not(no_global_oom_handling))]
use core::slice::from_raw_parts_mut;
use core::sync::atomic;
use core::sync::atomic::Ordering::{Acquire, Relaxed, Release};

#[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};
use crate::boxed::Box;
use crate::rc::is_dangling;
#[cfg(not(no_global_oom_handling))]
use crate::string::String;
#[cfg(not(no_global_oom_handling))]
use crate::vec::Vec;

#[cfg(test)]
mod tests;

/// 对 `Arc` 的引用数量的软限制。
///
/// 超过此限制将在 _exactly_ `MAX_REFCOUNT + 1` 引用处中止程序 (尽管不一定)。
///
/// 试图超越它可能会调用 `panic` (如果实际上没有超越它)。
///
/// 这是全局不，变体，在使用比较交换循环时也适用。
///
/// 请参见 `Arc::clone` 中的注释。
const MAX_REFCOUNT: usize = (isize::MAX) as usize;

/// 如果任一计数器达到 `MAX_REFCOUNT` 以上的错误，我们可以安全地 `panic`。
const INTERNAL_OVERFLOW_ERROR: &str = "Arc counter overflow";

#[cfg(not(sanitize = "thread"))]
macro_rules! acquire {
    ($x:expr) => {
        atomic::fence(Acquire)
    };
}

// ThreadSanitizer 不支持内存栅栏。
// 为避免在 Arc/Weak 实现中出现误报，请使用原子负载进行同步。
//
#[cfg(sanitize = "thread")]
macro_rules! acquire {
    ($x:expr) => {
        $x.load(Acquire)
    };
}

/// 线程安全的引用计数指针。`Arc` 代表原子引用计数。
///
/// `Arc<T>` 类型提供了在堆中分配的 `T` 类型值的共享所有权。在 `Arc` 上调用 [`clone`][clone] 会生成一个新的 `Arc` 实例，该实例指向堆上与源 `Arc` 相同的分配，同时增加了引用计数。
/// 当指向给定分配的最后一个 `Arc` 指针被销毁时，存储在该分配中的值 (通常称为 "内部值") 也将被丢弃。
///
/// 默认情况下，Rust 中的共享引用不允许可变的，`Arc` 也不例外：您通常无法获得 `Arc` 内部内容的可变引用。如果需要通过 `Arc` 进行可变的，请使用 [`Mutex`][mutex]，[`RwLock`][rwlock] 或 [`Atomic`][atomic] 类型之一。
///
/// **Note**: 此类型仅在支持原子加载和指针存储的平台上可用，其中包括支持 `std` crate 的所有平台，但并非所有仅支持 [`alloc`](crate) 的平台。
/// 这可以在编译时使用 `#[cfg(target_has_atomic = "ptr")]` 检测到。
///
/// ## 线程安全
///
/// 与 [`Rc<T>`] 不同，`Arc<T>` 使用原子操作进行引用计数。这意味着它是线程安全的。缺点是原子操作比普通的内存访问更昂贵。如果您不共享线程之间的引用计数分配，请考虑使用 [`Rc<T>`] 来降低开销。
/// [`Rc<T>`] 是一个安全的默认值，因为编译器会捕获在线程之间发送 [`Rc<T>`] 的任何尝试。
/// 但是，一个库可能会选择 `Arc<T>`，以便为库的消费者提供更大的灵活性。
///
/// 只要 `T` 实现 [`Send`] 和 [`Sync`]，`Arc<T>` 就会实现 [`Send`] 和 [`Sync`]。
/// 为什么不能在 `Arc<T>` 中放置非线程安全类型 `T` 使其成为线程安全的？ 起初这可能有点违反直觉：毕竟，`Arc<T>` 的重点不就是线程安全吗？ 关键在于: `Arc<T>` 使具有同一数据的多个所有权成为线程安全的，但并未为其数据增加线程安全。
///
/// 考虑 <code>Arc<[RefCell\<T>]></code>。
/// [`RefCell<T>`] 不是 [`Sync`]，如果 `Arc<T>` 总是 [`Send`]，那么 <code>Arc<[RefCell\<T>]></code> 也是。
/// 但是然后我们会遇到一个问题：
/// [`RefCell<T>`] 不是线程安全的； 它使用非原子操作来跟踪借用计数。
///
/// 最后，这意味着您可能需要将 `Arc<T>` 与某种 [`std::sync`] 类型 (通常为 [`Mutex<T>`][mutex]) 配对。
///
/// ## `Weak` 的中断循环
///
/// [`downgrade`][downgrade] 方法可用于创建非所有者 [`Weak`] 指针。[`Weak`] 指针可以 [`upgrade`][upgrade] 为 `Arc`，但如果存储在分配中的值已经被丢弃，这将返回 [`None`]。
/// 换句话说，`Weak` 指针不会使分配内部的值保持活动状态。然而，它们确实使分配（值的后备存储）保持活动状态。
///
/// `Arc` 指针之间的循环将永远不会被释放。
/// 因此，[`Weak`] 用于中断循环。例如，一棵树可能具有从父节点到子节点的强 `Arc` 指针，以及从子节点返回到其父节点的 [`Weak`] 指针。
///
/// # 克隆引用
///
/// 使用为 [`Arc<T>`][Arc] 和 [`Weak<T>`][Weak] 实现的 `Clone` trait 从现有的引用计数指针创建新的引用。
///
/// ```
/// use std::sync::Arc;
/// let foo = Arc::new(vec![1.0, 2.0, 3.0]);
/// // 以下两种语法是等效的。
/// let a = foo.clone();
/// let b = Arc::clone(&foo);
/// // a、b 和 foo 都是指向同一内存位置的 Arc
/// ```
///
/// ## `Deref` 行为
///
/// `Arc<T>` 自动取消对 `T` 的引用 (通过 [`Deref`][deref] trait)，因此您可以在类型为 `Arc<T>` 的值上调用 `T` 的方法。为了避免与 `T` 的方法名称冲突，`Arc<T>` 本身的方法是关联函数，使用 [完全限定语法][fully qualified syntax] 调用：
///
/// ```
/// use std::sync::Arc;
///
/// let my_arc = Arc::new(());
/// let my_weak = Arc::downgrade(&my_arc);
/// ```
///
/// `Arc<T>` 也可以使用完全限定语法来调用诸如 `Clone` 之类的 traits 实现。
/// 有些人喜欢使用完全限定的语法，而另一些人则喜欢使用方法调用语法。
///
/// ```
/// use std::sync::Arc;
///
/// let arc = Arc::new(());
/// // 方法调用语法
/// let arc2 = arc.clone();
/// // 完全限定的语法
/// let arc3 = Arc::clone(&arc);
/// ```
///
/// [`Weak<T>`][Weak] 不会自动解引用到 `T`，因为内部值可能已经被丢弃了。
///
/// [`Rc<T>`]: crate::rc::Rc
/// [clone]: Clone::clone
/// [mutex]: ../../std/sync/struct.Mutex.html
/// [rwlock]: ../../std/sync/struct.RwLock.html
/// [atomic]: core::sync::atomic
/// [deref]: core::ops::Deref
/// [downgrade]: Arc::downgrade
/// [upgrade]: Weak::upgrade
/// [RefCell\<T>]: core::cell::RefCell
/// [`RefCell<T>`]: core::cell::RefCell
/// [`std::sync`]: ../../std/sync/index.html
/// [`Arc::clone(&from)`]: Arc::clone
/// [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
///
/// # Examples
///
/// 在线程之间共享一些不可变数据：
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
// 请注意，我们 **不要** 在此处运行这些测试。
// 如果某个线程超过主线程，然后同时退出 (发生死锁)，则 windows 构建器会感到非常不满意，因此我们只是通过不运行这些测试来完全避免这种情况。
//
//
/// ```no_run
/// use std::sync::Arc;
/// use std::thread;
///
/// let five = Arc::new(5);
///
/// for _ in 0..10 {
///     let five = Arc::clone(&five);
///
///     thread::spawn(move || {
///         println!("{five:?}");
///     });
/// }
/// ```
///
/// 共享可变的 [`AtomicUsize`]：
///
/// [`AtomicUsize`]: core::sync::atomic::AtomicUsize "sync::atomic::AtomicUsize"
///
/// ```no_run
/// use std::sync::Arc;
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use std::thread;
///
/// let val = Arc::new(AtomicUsize::new(5));
///
/// for _ in 0..10 {
///     let val = Arc::clone(&val);
///
///     thread::spawn(move || {
///         let v = val.fetch_add(1, Ordering::SeqCst);
///         println!("{v:?}");
///     });
/// }
/// ```
///
/// 有关更多一般引用计数示例，请参见 [`rc` 文档][rc_examples]。
///
///
/// [rc_examples]: crate::rc#examples
#[cfg_attr(not(test), rustc_diagnostic_item = "Arc")]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Arc<T: ?Sized> {
    ptr: NonNull<ArcInner<T>>,
    phantom: PhantomData<ArcInner<T>>,
}

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

#[stable(feature = "catch_unwind", since = "1.9.0")]
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Arc<T> {}

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

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

impl<T: ?Sized> Arc<T> {
    unsafe fn from_inner(ptr: NonNull<ArcInner<T>>) -> Self {
        Self { ptr, phantom: PhantomData }
    }

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

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

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

#[unstable(feature = "coerce_unsized", issue = "18598")]
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> {}

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

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

    // 值 usize::MAX 充当临时 "locking" 升级弱指针或降级强指针的能力的标记。这用于避免在 `make_mut` 和 `get_mut` 中发生争夺。
    //
    //
    weak: atomic::AtomicUsize,

    data: T,
}

/// 使用内部值的布局计算 `ArcInner<T>` 的布局
fn arcinner_layout_for_value_layout(layout: Layout) -> Layout {
    // 使用给定的值布局计算布局。
    // 以前，在表达式 `&*(ptr as *const ArcInner<T>)` 上计算布局，但是这会产生未对齐的引用 (请参见 #54908)。
    //
    //
    Layout::new::<ArcInner<()>>().extend(layout).unwrap().0.pad_to_align()
}

unsafe impl<T: ?Sized + Sync + Send> Send for ArcInner<T> {}
unsafe impl<T: ?Sized + Sync + Send> Sync for ArcInner<T> {}

impl<T> Arc<T> {
    /// 创建一个新的 `Arc<T>`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new(data: T) -> Arc<T> {
        // 将弱指针计数开始为 1，这是所有强指针 (kinda) 所持有的弱指针，有关更多信息，请参见 std/rc.rs。
        //
        let x: Box<_> = Box::new(ArcInner {
            strong: atomic::AtomicUsize::new(1),
            weak: atomic::AtomicUsize::new(1),
            data,
        });
        unsafe { Self::from_inner(Box::leak(x).into()) }
    }

    /// 创建一个新的 `Arc<T>`，同时给您一个分配的 `Weak<T>`，以允许您创建一个 `T`，它持有一个指向自身的弱指针。
    ///
    /// 通常，直接或间接循环引用自身的结构体不应该对自身持有强引用以防止内存泄漏。
    /// 使用这个函数，您可以在 `T` 的初始化过程中，在 `Arc<T>` 创建之前访问弱指针，这样您就可以将它克隆并存储在 `T` 中。
    ///
    /// `new_cyclic` 先给 `Arc<T>` 分配托管分配，然后调用您的闭包，给这个分配一个 `Weak<T>`，然后再把您的闭包返回的 `T` 放入分配中，完成 `Arc<T>` 的构建。
    ///
    ///
    /// 由于新的 `Arc<T>` 在 `Arc<T>::new_cyclic` 返回之前尚未完全构造，因此在闭包内的弱引用上调用 [`upgrade`] 将失败并导致 `None` 值。
    ///
    /// # Panics
    ///
    /// 如果 `data_fn` 发生 panic，panic 会传播给调用者，而临时的 [`Weak<T>`] 会被正常丢弃。
    ///
    /// # Example
    ///
    /// ```
    /// # #![allow(dead_code)]
    /// use std::sync::{Arc, Weak};
    ///
    /// struct Gadget {
    ///     me: Weak<Gadget>,
    /// }
    ///
    /// impl Gadget {
    ///     /// 创建一个引用计数的 Gadget。
    ///     fn new() -> Arc<Self> {
    ///         // `me` 是指向我们正在构建的 `Arc` 的新分配的 `Weak<Gadget>`。
    /////
    ///         Arc::new_cyclic(|me| {
    ///             // 在此处创建实际的结构体。
    ///             Gadget { me: me.clone() }
    ///         })
    ///     }
    ///
    ///     /// 返回一个指向 Self 的引用计数指针。
    ///     fn me(&self) -> Arc<Self> {
    ///         self.me.upgrade().unwrap()
    ///     }
    /// }
    /// ```
    /// [`upgrade`]: Weak::upgrade
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "arc_new_cyclic", since = "1.60.0")]
    pub fn new_cyclic<F>(data_fn: F) -> Arc<T>
    where
        F: FnOnce(&Weak<T>) -> T,
    {
        // 在未初始化状态下用一个弱引用建造内部。
        //
        let uninit_ptr: NonNull<_> = Box::leak(Box::new(ArcInner {
            strong: atomic::AtomicUsize::new(0),
            weak: atomic::AtomicUsize::new(1),
            data: mem::MaybeUninit::<T>::uninit(),
        }))
        .into();
        let init_ptr: NonNull<ArcInner<T>> = uninit_ptr.cast();

        let weak = Weak { ptr: init_ptr };

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

        // 现在我们可以正确地初始化内部值，并将我们的弱引用变成强引用。
        //
        let strong = unsafe {
            let inner = init_ptr.as_ptr();
            ptr::write(ptr::addr_of_mut!((*inner).data), data);

            // 上面对数据字段的写操作对于任何观察到非零强引用计数的线程都必须可见。
            // 因此，我们至少需要 "Release" 排序才能与 `Weak::upgrade` 中的 `compare_exchange_weak` 同步。
            //
            // 无需排序 "Acquire"。
            // 考虑 `data_fn` 的可能行为时，我们只需要看一下对不可升级的 `Weak` 的引用可以做什么：
            //
            // - 它可以克隆 `Weak`，从而增加弱引用计数。
            // - 它可以丢弃这些克隆，从而减少弱引用计数 (但永远不会为零)。
            //
            // 这些副作用不会以任何方式影响我们，仅凭安全代码就不可能有其他副作用。
            //
            //
            let prev_value = (*inner).strong.fetch_add(1, Release);
            debug_assert_eq!(prev_value, 0, "No prior strong references should exist");

            Arc::from_inner(init_ptr)
        };

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

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

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

    /// 创建一个新的 `Pin<Arc<T>>`。
    /// 如果 `T` 未实现 `Unpin`，则 `data` 将被固定在内存中并且无法移动。
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "pin", since = "1.33.0")]
    #[must_use]
    pub fn pin(data: T) -> Pin<Arc<T>> {
        unsafe { Pin::new_unchecked(Arc::new(data)) }
    }

    /// 创建一个新的 `Pin<Arc<T>>`，如果分配失败则返回错误。
    #[unstable(feature = "allocator_api", issue = "32838")]
    #[inline]
    pub fn try_pin(data: T) -> Result<Pin<Arc<T>>, AllocError> {
        unsafe { Ok(Pin::new_unchecked(Arc::try_new(data)?)) }
    }

    /// 创建一个新的 `Arc<T>`，如果分配失败，则返回错误。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api)]
    /// use std::sync::Arc;
    ///
    /// let five = Arc::try_new(5)?;
    /// # Ok::<(), std::alloc::AllocError>(())
    /// ```
    #[unstable(feature = "allocator_api", issue = "32838")]
    #[inline]
    pub fn try_new(data: T) -> Result<Arc<T>, AllocError> {
        // 将弱指针计数开始为 1，这是所有强指针 (kinda) 所持有的弱指针，有关更多信息，请参见 std/rc.rs。
        //
        let x: Box<_> = Box::try_new(ArcInner {
            strong: atomic::AtomicUsize::new(1),
            weak: atomic::AtomicUsize::new(1),
            data,
        })?;
        unsafe { Ok(Self::from_inner(Box::leak(x).into())) }
    }

    /// 构造具有未初始化内容的新 `Arc`，如果分配失败，则返回错误。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit, allocator_api)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let mut five = Arc::<u32>::try_new_uninit()?;
    ///
    /// // 延迟初始化：
    /// Arc::get_mut(&mut five).unwrap().write(5);
    ///
    /// let five = unsafe { 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<Arc<mem::MaybeUninit<T>>, AllocError> {
        unsafe {
            Ok(Arc::from_ptr(Arc::try_allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate(layout),
                |mem| mem as *mut ArcInner<mem::MaybeUninit<T>>,
            )?))
        }
    }

    /// 创建一个具有未初始化内容的新 `Arc`，并用 `0` 字节填充内存，如果分配失败，则返回错误。
    ///
    ///
    /// 有关正确和不正确使用此方法的示例，请参见 [`MaybeUninit::zeroed`][zeroed]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit, allocator_api)]
    ///
    /// use std::sync::Arc;
    ///
    /// let zero = Arc::<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<Arc<mem::MaybeUninit<T>>, AllocError> {
        unsafe {
            Ok(Arc::from_ptr(Arc::try_allocate_for_layout(
                Layout::new::<T>(),
                |layout| Global.allocate_zeroed(layout),
                |mem| mem as *mut ArcInner<mem::MaybeUninit<T>>,
            )?))
        }
    }
    /// 如果 `Arc` 正好有一个强引用，则返回内部值。
    ///
    /// 否则，返回的 [`Err`] 将与传入的 `Arc` 相同。
    ///
    /// 即使存在突出的弱引用，此操作也将成功。
    ///
    /// 如果您不想将 `Arc` 保留在 [`Err`] 外壳中，强烈建议改用 [`Arc::into_inner`]。
    /// 立即抛弃 [`Err`] 有效，载荷，就像在表达式 `Arc::try_unwrap(this).ok()` 中一样，仍然可以导致强制使用计数抛弃为零，`Arc` 的内部值为抛弃:
    /// 例如，如果两个线程都在并行中执行这个表达式，那么就有一个竞争条件。
    /// 线程可以首先检查它们是否通过 `Arc::try_unwrap` 拥有它们的 `Arc` 的最后一个克隆，然后在调用中将它们的 `Arc` 丢弃到 [`ok`][`Result::ok`]，将强引用计数从 2 降为零。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let x = Arc::new(3);
    /// assert_eq!(Arc::try_unwrap(x), Ok(3));
    ///
    /// let x = Arc::new(4);
    /// let _y = Arc::clone(&x);
    /// assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[stable(feature = "arc_unique", since = "1.4.0")]
    pub fn try_unwrap(this: Self) -> Result<T, Self> {
        if this.inner().strong.compare_exchange(1, 0, Relaxed, Relaxed).is_err() {
            return Err(this);
        }

        acquire!(this.inner().strong);

        unsafe {
            let elem = ptr::read(&this.ptr.as_ref().data);

            // 做出弱指针以清除隐式的强 - 弱引用
            let _weak = Weak { ptr: this.ptr };
            mem::forget(this);

            Ok(elem)
        }
    }

    /// 如果 `Arc` 正好有一个强引用，则返回内部值。
    ///
    /// 否则，返回 [`None`]，`Arc` 为丢弃。
    ///
    /// 即使存在突出的弱引用，此操作也将成功。
    ///
    /// 如果在这个 `Arc` 的每个克隆上调用 `Arc::into_inner`，则可以保证恰好有一个调用返回内部值。
    /// 这特别意味着内部值不是丢弃。
    ///
    /// 类似的表达式 `Arc::try_unwrap(this).ok()` 不提供这样的保证。
    /// 请参见下面的最后一个示例和 [`Arc::try_unwrap`] 的文档。
    ///
    /// # Examples
    ///
    /// 演示 `Arc::into_inner` 提供的保证的最小示例。
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let x = Arc::new(3);
    /// let y = Arc::clone(&x);
    ///
    /// // 两个线程在 `Arc` 的两个克隆上调用 `Arc::into_inner`:
    /// let x_thread = std::thread::spawn(|| Arc::into_inner(x));
    /// let y_thread = std::thread::spawn(|| Arc::into_inner(y));
    ///
    /// let x_inner_value = x_thread.join().unwrap();
    /// let y_inner_value = y_thread.join().unwrap();
    ///
    /// // 其中一个线程保证接收到内部值:
    /// assert!(matches!(
    ///     (x_inner_value, y_inner_value),
    ///     (None, Some(3)) | (Some(3), None)
    /// ));
    /// // 如果线程改为调用 `Arc::try_unwrap(x).ok()` 和 `Arc::try_unwrap(y).ok()`，结果也可能是 `(None, None)`。
    /////
    /// ```
    ///
    /// 一个更实际的例子证明需要 `Arc::into_inner`:
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// // 使用 `Arc` 定义一个简单的单向链表:
    /// #[derive(Clone)]
    /// struct LinkedList<T>(Option<Arc<Node<T>>>);
    /// struct Node<T>(T, Option<Arc<Node<T>>>);
    ///
    /// // 丢掉依赖于 `Arc` 的析构函数的 long `LinkedList<T>` 会导致栈溢出。
    /// // 为了防止这种情况，我们可以提供一个手动的 `Drop` 实现，它在循环中进行销毁:
    /////
    /// impl<T> Drop for LinkedList<T> {
    ///     fn drop(&mut self) {
    ///         let mut link = self.0.take();
    ///         while let Some(arc_node) = link.take() {
    ///             if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {
    ///                 link = next;
    ///             }
    ///         }
    ///     }
    /// }
    ///
    /// // 省略 `new` 和 `push` 的实现
    /// impl<T> LinkedList<T> {
    ///     /* ... */
    /// #   fn new() -> Self {
    /// #       LinkedList(None)
    /// #   }
    /// #   fn push(&mut self, x: T) {
    /// #       self.0 = Some(Arc::new(Node(x, self.0.take())));
    /// #   }
    /// }
    ///
    /// // 如果 `Drop` impl 使用的是 `Arc::try_unwrap(arc).ok()` 而不是 `Arc::into_inner(arc)`，则尽管手动 `Drop` impl，以下代码仍可能导致栈溢出。
    /////
    /////
    ///
    /// // 创建一个长列表并克隆它
    /// let mut x = LinkedList::new();
    /// for i in 0..100000 {
    ///     x.push(i); // 将 i 添加到 x 的前面
    /// }
    /// let y = x.clone();
    ///
    /// // 丢弃并行中的克隆人
    /// let x_thread = std::thread::spawn(|| drop(x));
    /// let y_thread = std::thread::spawn(|| drop(y));
    /// x_thread.join().unwrap();
    /// y_thread.join().unwrap();
    /// ```
    #[inline]
    #[stable(feature = "arc_into_inner", since = "1.70.0")]
    pub fn into_inner(this: Self) -> Option<T> {
        // 确保普通的 `Drop` 实现也没有被调用
        let mut this = mem::ManuallyDrop::new(this);

        // 执行 `drop` 和 `drop_slow` 之后
        if this.inner().strong.fetch_sub(1, Release) != 1 {
            return None;
        }

        acquire!(this.inner().strong);

        // SAFETY: 这反映了该行
        //
        //     unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) };
        //
        // in `drop_slow`.
        // 不是丢弃指针后面的值，而是读取并最终返回; `ptr::read` 具有与 `ptr::drop_in_place` 相同的安全条件。
        //
        let inner = unsafe { ptr::read(Self::get_mut_unchecked(&mut this)) };

        drop(Weak { ptr: this.ptr });

        Some(inner)
    }
}

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

    /// 创建一个具有未初始化内容的新原子引用计数切片，内存中填充 `0` 字节。
    ///
    ///
    /// 有关正确和不正确使用此方法的示例，请参见 [`MaybeUninit::zeroed`][zeroed]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    ///
    /// use std::sync::Arc;
    ///
    /// let values = Arc::<[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))]
    #[inline]
    #[unstable(feature = "new_uninit", issue = "63291")]
    #[must_use]
    pub fn new_zeroed_slice(len: usize) -> Arc<[mem::MaybeUninit<T>]> {
        unsafe {
            Arc::from_ptr(Arc::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 ArcInner<[mem::MaybeUninit<T>]>
                },
            ))
        }
    }
}

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

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

impl<T: ?Sized> Arc<T> {
    /// 消耗 `Arc`，返回包装的指针。
    ///
    /// 为避免内存泄漏，必须使用 [`Arc::from_raw`] 将指针转换回 `Arc`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let x = Arc::new("hello".to_owned());
    /// let x_ptr = Arc::into_raw(x);
    /// assert_eq!(unsafe { &*x_ptr }, "hello");
    /// ```
    #[must_use = "losing the pointer will leak memory"]
    #[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
    }

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

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

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

            // 反转偏移量以找到原始的 ArcInner。
            let arc_ptr = ptr.byte_sub(offset) as *mut ArcInner<T>;

            Self::from_ptr(arc_ptr)
        }
    }

    /// 创建一个指向该分配的新 [`Weak`] 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// let weak_five = Arc::downgrade(&five);
    /// ```
    #[must_use = "this returns a new `Weak` pointer, \
                  without modifying the original `Arc`"]
    #[stable(feature = "arc_weak", since = "1.4.0")]
    pub fn downgrade(this: &Self) -> Weak<T> {
        // 可以使用 `Relaxed`，因为我们正在检查以下 CAS 中的值。
        //
        let mut cur = this.inner().weak.load(Relaxed);

        loop {
            // 检查弱引用计数当前是否为 "locked"； 如果是这样，spin。
            if cur == usize::MAX {
                hint::spin_loop();
                cur = this.inner().weak.load(Relaxed);
                continue;
            }

            // 我们不能让引用计数增加太多超过 `MAX_REFCOUNT`。
            assert!(cur <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR);

            // NOTE: 该代码当前忽略了溢出到 usize::MAX 的可能性； 通常，Rc 和 Arc 都需要进行调整以应对溢出。
            //
            //

            // 与 Clone() 不同，我们需要将其作为 Acquire 读取，以与来自 `is_unique` 的写入同步，以便该写入之前的事件在此读取之前发生。
            //
            //
            match this.inner().weak.compare_exchange_weak(cur, cur + 1, Acquire, Relaxed) {
                Ok(_) => {
                    // 确保我们不会创建悬垂的 Weak
                    debug_assert!(!is_dangling(this.ptr.as_ptr()));
                    return Weak { ptr: this.ptr };
                }
                Err(old) => cur = old,
            }
        }
    }

    /// 获取指向该分配的 [`Weak`] 指针的数量。
    ///
    /// # Safety
    ///
    /// 此方法本身是安全的，但正确使用它需要格外小心。
    /// 另一个线程可以随时更改弱引用计数，包括潜在地在调用此方法与对结果进行操作之间。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    /// let _weak_five = Arc::downgrade(&five);
    ///
    /// // 此断言是确定性的，因为我们尚未在线程之间共享 `Arc` 或 `Weak`。
    /////
    /// assert_eq!(1, Arc::weak_count(&five));
    /// ```
    #[inline]
    #[must_use]
    #[stable(feature = "arc_counts", since = "1.15.0")]
    pub fn weak_count(this: &Self) -> usize {
        let cnt = this.inner().weak.load(Acquire);
        // 如果弱引用计数当前处于锁定状态，则在进行锁定之前，该计数的值为 0。
        //
        if cnt == usize::MAX { 0 } else { cnt - 1 }
    }

    /// 获取指向此分配的强 (`Arc`) 指针的数量。
    ///
    /// # Safety
    ///
    /// 此方法本身是安全的，但正确使用它需要格外小心。
    /// 另一个线程可以随时更改强引用计数，包括潜在地在调用此方法与对结果进行操作之间。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    /// let _also_five = Arc::clone(&five);
    ///
    /// // 此断言是确定性的，因为我们尚未在线程之间共享 `Arc`。
    /////
    /// assert_eq!(2, Arc::strong_count(&five));
    /// ```
    #[inline]
    #[must_use]
    #[stable(feature = "arc_counts", since = "1.15.0")]
    pub fn strong_count(this: &Self) -> usize {
        this.inner().strong.load(Acquire)
    }

    /// 与提供的指针关联的 `Arc<T>` 上的强引用计数加 1。
    ///
    /// # Safety
    ///
    /// 指针必须已经通过 `Arc::into_raw` 获得，并且关联的 `Arc` 实例必须有效 (即
    /// 在此方法的持续时间内，强引用计数必须至少为 1)。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// unsafe {
    ///     let ptr = Arc::into_raw(five);
    ///     Arc::increment_strong_count(ptr);
    ///
    ///     // 此断言是确定性的，因为我们尚未在线程之间共享 `Arc`。
    /////
    ///     let five = Arc::from_raw(ptr);
    ///     assert_eq!(2, Arc::strong_count(&five));
    /// }
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")]
    pub unsafe fn increment_strong_count(ptr: *const T) {
        // 保留 Arc，但不要通过包装在 ManuallyDrop 中来接触引用计数
        let arc = unsafe { mem::ManuallyDrop::new(Arc::<T>::from_raw(ptr)) };
        // 现在增加引用计数，但也不要丢弃新的引用计数
        let _arc_clone: mem::ManuallyDrop<_> = arc.clone();
    }

    /// 将与提供的指针关联的 `Arc<T>` 上的强引用计数减 1。
    ///
    /// # Safety
    ///
    /// 指针必须已经通过 `Arc::into_raw` 获得，并且关联的 `Arc` 实例必须有效 (即
    /// 调用此方法时，强引用计数必须至少为 1)。
    /// 此方法可用于释放最终的 `Arc` 和后备存储，但不应在最终的 `Arc` 释放后调用。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// unsafe {
    ///     let ptr = Arc::into_raw(five);
    ///     Arc::increment_strong_count(ptr);
    ///
    ///     // 这些断言是确定性的，因为我们尚未在线程之间共享 `Arc`。
    /////
    ///     let five = Arc::from_raw(ptr);
    ///     assert_eq!(2, Arc::strong_count(&five));
    ///     Arc::decrement_strong_count(ptr);
    ///     assert_eq!(1, Arc::strong_count(&five));
    /// }
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")]
    pub unsafe fn decrement_strong_count(ptr: *const T) {
        unsafe { drop(Arc::from_raw(ptr)) };
    }

    #[inline]
    fn inner(&self) -> &ArcInner<T> {
        // 这种不安全的做法是可以的，因为当此 Arc 处于活动状态时，我们可以保证内部指针是有效的。
        // 此外，我们知道 `ArcInner` 结构体本身就是 `Sync`，因为内部数据也是 `Sync`，所以我们可以借用一个不可变的指针指向这些内容。
        //
        //
        //
        unsafe { self.ptr.as_ref() }
    }

    // `drop` 的非内联部分。
    #[inline(never)]
    unsafe fn drop_slow(&mut self) {
        // 此时的数据，即使我们不能释放 box 分配本身 (可能仍然存在弱指针)。
        //
        unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) };

        // 丢弃所有强引用共同持有的弱引用
        drop(Weak { ptr: self.ptr });
    }

    /// 如果两个 `Arc` 以类似于 [`ptr::eq`] 的方式指向相同的分配，则返回 `true`。
    /// 比较 `dyn Trait` 指针时的注意事项，请参见 [that function][`ptr::eq`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    /// let same_five = Arc::clone(&five);
    /// let other_five = Arc::new(5);
    ///
    /// assert!(Arc::ptr_eq(&five, &same_five));
    /// assert!(!Arc::ptr_eq(&five, &other_five));
    /// ```
    ///
    /// [`ptr::eq`]: core::ptr::eq "ptr::eq"
    #[inline]
    #[must_use]
    #[stable(feature = "ptr_eq", since = "1.17.0")]
    pub fn ptr_eq(this: &Self, other: &Self) -> bool {
        this.ptr.as_ptr() == other.ptr.as_ptr()
    }
}

impl<T: ?Sized> Arc<T> {
    /// 为 `ArcInner<T>` 分配足够的空间，以容纳可能未定义大小的内部值，其中该值具有提供的布局。
    ///
    /// 函数 `mem_to_arcinner` 用数据指针调用，并且必须返回 `ArcInner<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_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>,
    ) -> *mut ArcInner<T> {
        let layout = arcinner_layout_for_value_layout(value_layout);

        let ptr = allocate(layout).unwrap_or_else(|_| handle_alloc_error(layout));

        unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) }
    }

    /// 为 `ArcInner<T>` 分配足够的空间，以容纳可能未定义大小的内部值 (该值具有提供的布局)，如果分配失败，则返回错误。
    ///
    ///
    /// 函数 `mem_to_arcinner` 用数据指针调用，并且必须返回 `ArcInner<T>` 的 (可能是胖的) 指针。
    ///
    ///
    unsafe fn try_allocate_for_layout(
        value_layout: Layout,
        allocate: impl FnOnce(Layout) -> Result<NonNull<[u8]>, AllocError>,
        mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>,
    ) -> Result<*mut ArcInner<T>, AllocError> {
        let layout = arcinner_layout_for_value_layout(value_layout);

        let ptr = allocate(layout)?;

        let inner = unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) };

        Ok(inner)
    }

    unsafe fn initialize_arcinner(
        ptr: NonNull<[u8]>,
        layout: Layout,
        mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>,
    ) -> *mut ArcInner<T> {
        let inner = mem_to_arcinner(ptr.as_non_null_ptr().as_ptr());
        debug_assert_eq!(unsafe { Layout::for_value(&*inner) }, layout);

        unsafe {
            ptr::write(&mut (*inner).strong, atomic::AtomicUsize::new(1));
            ptr::write(&mut (*inner).weak, atomic::AtomicUsize::new(1));
        }

        inner
    }

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

    #[cfg(not(no_global_oom_handling))]
    fn from_box(v: Box<T>) -> Arc<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).data as *mut _ as *mut u8,
                value_size,
            );

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

            Self::from_ptr(ptr)
        }
    }
}

impl<T> Arc<[T]> {
    /// 用给定的长度分配 `ArcInner<[T]>`。
    #[cfg(not(no_global_oom_handling))]
    unsafe fn allocate_for_slice(len: usize) -> *mut ArcInner<[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 ArcInner<[T]>,
            )
        }
    }

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

            ptr::copy_nonoverlapping(v.as_ptr(), &mut (*ptr).data as *mut [T] as *mut T, v.len());

            Self::from_ptr(ptr)
        }
    }

    /// 从已知为一定大小的迭代器构造 `Arc<[T]>`。
    ///
    /// 如果大小错误，则行为是未定义的。
    #[cfg(not(no_global_oom_handling))]
    unsafe fn from_iter_exact(iter: impl Iterator<Item = T>, len: usize) -> Arc<[T]> {
        // 在克隆 T 元素时 panic 守卫。
        // 如果出现 panic，将丢弃已写入新 ArcInner 的元素，然后释放内存。
        //
        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).data 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;
            }

            // 全部清空。忘记守卫，这样它就不会释放新的 ArcInner。
            mem::forget(guard);

            Self::from_ptr(ptr)
        }
    }
}

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

#[cfg(not(no_global_oom_handling))]
impl<T: Clone> ArcFromSlice<T> for Arc<[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> ArcFromSlice<T> for Arc<[T]> {
    #[inline]
    fn from_slice(v: &[T]) -> Self {
        unsafe { Arc::copy_from_slice(v) }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Clone for Arc<T> {
    /// 克隆 `Arc` 指针。
    ///
    /// 这将创建另一个指向相同分配的指针，从而增加了强引用计数。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// let _ = Arc::clone(&five);
    /// ```
    #[inline]
    fn clone(&self) -> Arc<T> {
        // 这里可以使用宽松的排序，因为了解原始引用可以防止其他线程错误地删除对象。
        //
        // 如 [Boost 文档][1] 中所述，可以始终通过 memory_order_relaxed 来完成增加引用计数器的操作：对对象的新引用只能由现有引用形成，并且将现有引用从一个线程传递到另一个线程必须已经提供了所需的同步。
        //
        //
        // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html)
        //
        //
        //
        //
        //
        let old_size = self.inner().strong.fetch_add(1, Relaxed);

        // 但是，，我们需要防止大量的引用计数，以防有人 `mem::forget` 了 Arc。
        // 如果我们不这样做，那么计数可能会溢出，并且用户将随心所欲的使用。
        // 在任何实际程序中都不会采用此分支。
        // 我们中止是因为这样的程序令人难以置信的退化了，我们不想再支持它。
        //
        // 此检查并非 100% 防水: 当引用计数超过 `isize::MAX` 时，我们会出错。
        // 但是我们在完成增量之后 * 进行检查，所以这里有可能最坏的情况已经发生，我们实际上确实溢出了 `usize` 计数器。
        //
        // 但是，这需要计数器在上面的增量和下面的 `abort` 之间从 `isize::MAX` 增长到 `usize::MAX`，这似乎极不可能。
        //
        // 这是全局，不变量，也适用于在其他方法中使用比较交换循环来递增计数器时。
        // 否则，可以使用比较交换循环使计数器几乎溢出，然后使用几个 `fetch_add` 溢出。
        //
        //
        //
        if old_size > MAX_REFCOUNT {
            abort();
        }

        unsafe { Self::from_inner(self.ptr) }
    }
}

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

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

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

impl<T: Clone> Arc<T> {
    /// 对给定的 `Arc` 进行可变引用。
    ///
    /// 如果有其他 `Arc` 指针指向同一分配，则 `make_mut` 会将内部值 [`clone`] 到新分配以确保唯一的所有权。
    /// 这也称为写时克隆。
    ///
    /// 但是，如果没有其他 `Arc` 指针指向这个分配，而是一些 [`Weak`] 指针，那么 [`Weak`] 指针将被分离，内部值不会被克隆。
    ///
    ///
    /// 另请参见 [`get_mut`]，它将失败而不是克隆内部值或分离 [`Weak`] 指针。
    ///
    /// [`clone`]: Clone::clone
    /// [`get_mut`]: Arc::get_mut
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let mut data = Arc::new(5);
    ///
    /// *Arc::make_mut(&mut data) += 1;         // 不会克隆任何东西
    /// let mut other_data = Arc::clone(&data); // 不会克隆内部数据
    /// *Arc::make_mut(&mut data) += 1;         // 克隆内部数据
    /// *Arc::make_mut(&mut data) += 1;         // 不会克隆任何东西
    /// *Arc::make_mut(&mut other_data) *= 2;   // 不会克隆任何东西
    ///
    /// // 现在，`data` 和 `other_data` 指向不同的分配。
    /// assert_eq!(*data, 8);
    /// assert_eq!(*other_data, 12);
    /// ```
    ///
    /// [`Weak`] 指针将被分离:
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let mut data = Arc::new(75);
    /// let weak = Arc::downgrade(&data);
    ///
    /// assert!(75 == *data);
    /// assert!(75 == *weak.upgrade().unwrap());
    ///
    /// *Arc::make_mut(&mut data) += 1;
    ///
    /// assert!(76 == *data);
    /// assert!(weak.upgrade().is_none());
    /// ```
    ///
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "arc_unique", since = "1.4.0")]
    pub fn make_mut(this: &mut Self) -> &mut T {
        // 请注意，我们同时拥有强引用和弱引用。
        // 因此，仅释放我们强大的引用本身不会导致内存被释放。
        //
        // 使用 Acquire 来确保我们看到在发行版对 `strong` 进行写入 (即递减) 之前发生的对 `weak` 的写入。
        // 由于数量不多，因此 ArcInner 本身不可能被释放。
        //
        //
        //
        if this.inner().strong.compare_exchange(1, 0, Acquire, Relaxed).is_err() {
            // 存在另一个强大的指针，因此我们必须进行克隆。
            // 预分配内存以允许直接写入克隆的值。
            let mut arc = Self::new_uninit();
            unsafe {
                let data = Arc::get_mut_unchecked(&mut arc);
                (**this).write_clone_into_raw(data.as_mut_ptr());
                *this = arc.assume_init();
            }
        } else if this.inner().weak.load(Relaxed) != 1 {
            // 上面的 relaxed 足以满足需要，因为这从根本上来说是一种优化：我们总是在与被丢弃的弱指针赛跑。
            // 最坏的情况是，我们最终不必要地分配了新的 Arc。
            //

            // 我们删除了最后一个强引用，但还剩下其他弱引用。
            // 我们将内容移动到新的 Arc，并使其他弱引用无效。
            //

            // 请注意，读取 `weak` 不可能产生 usize::MAX (即已锁定)，因为弱引用计数只能由带有强引用的线程锁定。
            //
            //

            // 实现我们自己的隐式弱指针，以便可以根据需要清理 ArcInner。
            //
            let _weak = Weak { ptr: this.ptr };

            // 只能窃取数据，剩下的就是 Weaks
            let mut arc = Self::new_uninit();
            unsafe {
                let data = Arc::get_mut_unchecked(&mut arc);
                data.as_mut_ptr().copy_from_nonoverlapping(&**this, 1);
                ptr::write(this, arc.assume_init());
            }
        } else {
            // 我们是任何一种形式的唯一引用。增加强引用计数。
            //
            this.inner().strong.store(1, Release);
        }

        // 与 `get_mut()` 一样，这种不安全性也是可以的，因为我们的引用一开始是唯一的，或者在克隆内容时成为一体。
        //
        unsafe { Self::get_mut_unchecked(this) }
    }

    /// 如果我们有 `T` 的唯一引用，那就打开它。否则，克隆 `T` 并返回克隆。
    ///
    /// 假设 `arc_t` 是 `Arc<T>` 类型，这个函数在功能上等同于 `(*arc_t).clone()`，但会尽可能避免克隆内部值。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(arc_unwrap_or_clone)]
    /// # use std::{ptr, sync::Arc};
    /// let inner = String::from("test");
    /// let ptr = inner.as_ptr();
    ///
    /// let arc = Arc::new(inner);
    /// let inner = Arc::unwrap_or_clone(arc);
    /// // 内部值没有被克隆
    /// assert!(ptr::eq(ptr, inner.as_ptr()));
    ///
    /// let arc = Arc::new(inner);
    /// let arc2 = arc.clone();
    /// let inner = Arc::unwrap_or_clone(arc);
    /// // 因为有两个引用，我们不得不克隆内部值。
    /// assert!(!ptr::eq(ptr, inner.as_ptr()));
    /// // `arc2` 是最后一个引用，所以当我们展开它时，我们会得到原来的 `String`。
    /////
    /// let inner = Arc::unwrap_or_clone(arc2);
    /// assert!(ptr::eq(ptr, inner.as_ptr()));
    /// ```
    ///
    #[inline]
    #[unstable(feature = "arc_unwrap_or_clone", issue = "93610")]
    pub fn unwrap_or_clone(this: Self) -> T {
        Arc::try_unwrap(this).unwrap_or_else(|arc| (*arc).clone())
    }
}

impl<T: ?Sized> Arc<T> {
    /// 如果没有其他 `Arc` 或 [`Weak`] 指向相同分配的指针，则返回给定 `Arc` 的可变引用。
    ///
    ///
    /// 否则返回 [`None`]，因为更改共享值并不安全。
    ///
    /// 另见 [`make_mut`][make_mut]，当有其他 `Arc` 指针时，它将 [`clone`][clone] 内部值。
    ///
    /// [make_mut]: Arc::make_mut
    /// [clone]: Clone::clone
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let mut x = Arc::new(3);
    /// *Arc::get_mut(&mut x).unwrap() = 4;
    /// assert_eq!(*x, 4);
    ///
    /// let _y = Arc::clone(&x);
    /// assert!(Arc::get_mut(&mut x).is_none());
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "arc_unique", since = "1.4.0")]
    pub fn get_mut(this: &mut Self) -> Option<&mut T> {
        if this.is_unique() {
            // 这种不安全性是可以的，因为我们保证返回的指针是将永远返回到 T 的 *only* 指针。
            // 此时，我们的引数保证为 1，并且我们要求 Arc 本身为 `mut`，因此我们将唯一可能的引数返回给内部数据。
            //
            //
            //
            unsafe { Some(Arc::get_mut_unchecked(this)) }
        } else {
            None
        }
    }

    /// 将变量引用返回给定的 `Arc`，而不进行任何检查。
    ///
    /// 另请参见 [`get_mut`]，它是安全的并且进行适当的检查。
    ///
    /// [`get_mut`]: Arc::get_mut
    ///
    /// # Safety
    ///
    /// 如果存在指向同一分配的任何其他 `Arc` 或 [`Weak`] 指针，则在返回的借用期间，它们不得被解引用或具有活动借用，并且它们的内部类型必须与此 Rc 的内部类型完全相同 (包括生命周)。
    /// 如果不存在这样的指针 (例如紧接在 `Arc::new` 之后)，则情况很简单。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let mut x = Arc::new(String::new());
    /// unsafe {
    ///     Arc::get_mut_unchecked(&mut x).push_str("foo")
    /// }
    /// assert_eq!(*x, "foo");
    /// ```
    /// 指向同一分配的其他 `Arc` 指针必须指向同一类型。
    ///
    /// ```no_run
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let x: Arc<str> = Arc::from("Hello, world!");
    /// let mut y: Arc<[u8]> = x.clone().into();
    /// unsafe {
    ///     // 这是未定义的行为，因为 x 的内部类型是 str，而不是 [u8]
    ///     Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff 在 UTF-8 中无效
    /// }
    /// println!("{}", &*x); // str 中的 UTF-8 无效
    /// ```
    ///
    /// 指向同一分配的其他 `Arc` 指针必须指向完全相同的类型，包括生命周期。
    ///
    /// ```no_run
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let x: Arc<&str> = Arc::new("Hello, world!");
    /// {
    ///     let s = String::from("Oh, no!");
    ///     let mut y: Arc<&str> = x.clone().into();
    ///     unsafe {
    ///         // 这是未定义的行为，因为 x 的内部类型是 &'long str，而不是 &'short str
    /////
    ///         *Arc::get_mut_unchecked(&mut y) = &s;
    ///     }
    /// }
    /// println!("{}", &*x); // Use-after-free
    /// ```
    ///
    #[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()).data }
    }

    /// 确定这是否是底层数据的唯一引用 (包括弱引用)。
    ///
    ///
    /// 请注意，这需要锁定弱引用计数。
    fn is_unique(&mut self) -> bool {
        // 如果我们似乎是唯一的弱指针持有者，则锁定弱指针计数。
        //
        // 在这里，获取标签可确保在 `weak` 计数递减之前 (通过使用释放的 `Weak::drop`) 与对 `strong` (特别是 `Weak::upgrade`) 的任何写操作发生事前关联。
        // 如果升级后的弱引用从未被丢弃，这里的 CAS 将失败，所以我们不关心同步。
        //
        //
        //
        if self.inner().weak.compare_exchange(1, usize::MAX, Acquire, Relaxed).is_ok() {
            // 它必须是 `Acquire`，才能与 `drop` 中 `strong` 计数器的减量同步 - 唯一的访问是在丢弃最后一个引用以外的任何内容时发生的。
            //
            //
            let unique = self.inner().strong.load(Acquire) == 1;

            // 此处的释放写入与 `downgrade` 中的读取同步，从而有效防止了 `strong` 的上述读取在写入后发生。
            //
            //
            self.inner().weak.store(1, Release); // 释放锁
            unique
        } else {
            false
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<#[may_dangle] T: ?Sized> Drop for Arc<T> {
    /// 丢弃 `Arc`。
    ///
    /// 这将减少强引用计数。
    /// 如果强引用计数达到零，那么唯一的其他引用 (如果有) 是 [`Weak`]，因此我们将 `drop` 作为内部值。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// struct Foo;
    ///
    /// impl Drop for Foo {
    ///     fn drop(&mut self) {
    ///         println!("dropped!");
    ///     }
    /// }
    ///
    /// let foo  = Arc::new(Foo);
    /// let foo2 = Arc::clone(&foo);
    ///
    /// drop(foo);    // 不打印任何东西
    /// drop(foo2);   // 打印 "dropped!"
    /// ```
    #[inline]
    fn drop(&mut self) {
        // 因为 `fetch_sub` 已经是原子的，所以除非要删除对象，否则不需要与其他线程同步。
        // 此逻辑适用于以下 `fetch_sub` 至 `weak` 计数。
        //
        if self.inner().strong.fetch_sub(1, Release) != 1 {
            return;
        }

        // 需要使用该栅栏来防止对数据使用进行重新排序和删除数据。
        // 因为标记为 `Release`，引用计数的减少与这个 `Acquire` 栅栏同步。
        // 这意味着数据的使用发生在减少引用计数之前，这发生在此栅栏之前，发生在删除数据之前。
        //
        // 如 [Boost 文档][1] 中所述，
        //
        // > 在一个对象中强制执行对对象的任何可能的访问很重要
        // > *删除之前将线程 (通过现有引用) 连接到* happen
        // > 该对象位于另一个线程中。这是通过 "release" 实现的
        // > 丢弃引用 (对对象的任何访问权限) 后的操作
        // > 通过此引用显然必须发生在之前)，并且
        // > 删除对象前的 "acquire" 操作。
        //
        // 特别是，虽然 Arc 的内容通常是不可变的，但可以对 Mutex<T> 之类的内容进行内部写入。
        // 由于在删除互斥锁时未获得互斥锁，因此我们不能依靠其同步逻辑使线程 A 中的析构函数看到线程 A 中的写入。
        //
        //
        // 还要注意，这里的 Acquire 栅栏可能会被 Acquire 负载所取代，这可以提高在激烈竞争的情况下的性能。请参见 [2]。
        //
        // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html)
        // [2]: (https://github.com/rust-lang/rust/pull/41714)
        //
        //
        //
        //
        //
        //
        //
        acquire!(self.inner().strong);

        unsafe {
            self.drop_slow();
        }
    }
}

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

    /// 将 `Arc<dyn Any + Send + Sync>` 向下转换为具体类型。
    ///
    /// 有关安全的替代方案，请参见 [`downcast`]。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(downcast_unchecked)]
    ///
    /// use std::any::Any;
    /// use std::sync::Arc;
    ///
    /// let x: Arc<dyn Any + Send + Sync> = Arc::new(1_usize);
    ///
    /// unsafe {
    ///     assert_eq!(*x.downcast_unchecked::<usize>(), 1);
    /// }
    /// ```
    ///
    /// # Safety
    ///
    /// 包含的值必须是 `T` 类型。
    /// 使用不正确的类型调用此方法是 *未定义的行为*。
    ///
    ///
    /// [`downcast`]: Self::downcast
    #[inline]
    #[unstable(feature = "downcast_unchecked", issue = "90850")]
    pub unsafe fn downcast_unchecked<T>(self) -> Arc<T>
    where
        T: Any + Send + Sync,
    {
        unsafe {
            let ptr = self.ptr.cast::<ArcInner<T>>();
            mem::forget(self);
            Arc::from_inner(ptr)
        }
    }
}

impl<T> Weak<T> {
    /// 创建一个新的 `Weak<T>`，而不分配任何内存。
    /// 在返回值上调用 [`upgrade`] 总是得到 [`None`]。
    ///
    /// [`upgrade`]: Weak::upgrade
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Weak;
    ///
    /// let empty: Weak<i64> = Weak::new();
    /// assert!(empty.upgrade().is_none());
    /// ```
    #[stable(feature = "downgraded_weak", since = "1.10.0")]
    #[rustc_const_unstable(feature = "const_weak_new", issue = "95091", reason = "recently added")]
    #[must_use]
    pub const fn new() -> Weak<T> {
        Weak { ptr: unsafe { NonNull::new_unchecked(ptr::invalid_mut::<ArcInner<T>>(usize::MAX)) } }
    }
}

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

impl<T: ?Sized> Weak<T> {
    /// 返回对此 `Weak<T>` 指向的对象 `T` 的裸指针。
    ///
    /// 该指针仅在有一些强引用时才有效。
    /// 指针可能是悬垂的，未对齐的，甚至是 [`null`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    /// use std::ptr;
    ///
    /// let strong = Arc::new("hello".to_owned());
    /// let weak = Arc::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 "ptr::null"
    #[must_use]
    #[stable(feature = "weak_into_raw", since = "1.45.0")]
    pub fn as_ptr(&self) -> *const T {
        let ptr: *mut ArcInner<T> = NonNull::as_ptr(self.ptr);

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

    /// 消耗 `Weak<T>` 并将其转换为裸指针。
    ///
    /// 这会将弱指针转换为裸指针，同时仍保留一个弱引用的所有权 (此操作不会修改弱引用计数)。
    /// 可以将其转换回带有 [`from_raw`] 的 `Weak<T>`。
    ///
    /// 与 [`as_ptr`] 一样，访问指针目标的限制也适用。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::{Arc, Weak};
    ///
    /// let strong = Arc::new("hello".to_owned());
    /// let weak = Arc::downgrade(&strong);
    /// let raw = weak.into_raw();
    ///
    /// assert_eq!(1, Arc::weak_count(&strong));
    /// assert_eq!("hello", unsafe { &*raw });
    ///
    /// drop(unsafe { Weak::from_raw(raw) });
    /// assert_eq!(0, Arc::weak_count(&strong));
    /// ```
    ///
    /// [`from_raw`]: Weak::from_raw
    /// [`as_ptr`]: Weak::as_ptr
    ///
    ///
    #[must_use = "`self` will be dropped if the result is not used"]
    #[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::sync::{Arc, Weak};
    ///
    /// let strong = Arc::new("hello".to_owned());
    ///
    /// let raw_1 = Arc::downgrade(&strong).into_raw();
    /// let raw_2 = Arc::downgrade(&strong).into_raw();
    ///
    /// assert_eq!(2, Arc::weak_count(&strong));
    ///
    /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap());
    /// assert_eq!(1, Arc::weak_count(&strong));
    ///
    /// drop(strong);
    ///
    /// // 减少最后一个弱引用计数。
    /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());
    /// ```
    ///
    /// [`new`]: Weak::new
    /// [`into_raw`]: Weak::into_raw
    /// [`upgrade`]: Weak::upgrade
    ///
    ///
    ///
    #[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) {
            // 这是悬垂的 Weak。
            ptr as *mut ArcInner<T>
        } else {
            // 否则，我们保证指针来自无悬挂的弱。
            // SAFETY: data_offset 可以安全调用，因为 ptr 引用了一个真实的 (可能已丢弃) 的 T。
            let offset = unsafe { data_offset(ptr) };
            // 因此，我们反转偏移量以获得整个 RcBox。
            // SAFETY: 指针源自 Weak，因此此偏移量是安全的。
            unsafe { ptr.byte_sub(offset) as *mut ArcInner<T> }
        };

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

impl<T: ?Sized> Weak<T> {
    /// 尝试将 `Weak` 指针升级到 [`Arc`]，如果成功，则延迟内部值的丢弃。
    ///
    ///
    /// 如果内部值已经被丢弃，则返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// let weak_five = Arc::downgrade(&five);
    ///
    /// let strong_five: Option<Arc<_>> = weak_five.upgrade();
    /// assert!(strong_five.is_some());
    ///
    /// // 销毁所有强指针。
    /// drop(strong_five);
    /// drop(five);
    ///
    /// assert!(weak_five.upgrade().is_none());
    /// ```
    #[must_use = "this returns a new `Arc`, \
                  without modifying the original weak pointer"]
    #[stable(feature = "arc_weak", since = "1.4.0")]
    pub fn upgrade(&self) -> Option<Arc<T>> {
        // 我们使用 CAS 循环而不是 fetch_add 来增加强引用计数，因为此函数绝不应该将引用计数从零变为一。
        //
        //
        self.inner()?
            .strong
            // 对于失败案例，放宽是可以的，因为我们对新状态没有任何期望。
            // 如果可以在创建 `Weak` 引用后初始化内部值，则成功案例需要与 `Arc::new_cyclic` 同步进行获取。
            // 在这种情况下，我们希望观察到完全初始化的值。
            //
            .fetch_update(Acquire, Relaxed, |n| {
                // 我们可以观察到的任何写入 0 都会使该字段永久处于零状态。
                if n == 0 {
                    return None;
                }
                // 请参见 `Arc::clone` 中的注释以了解执行此操作的原因 (对于 `mem::forget`)。
                assert!(n <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR);
                Some(n + 1)
            })
            .ok()
            // 在上面检查为空
            .map(|_| unsafe { Arc::from_inner(self.ptr) })
    }

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

    /// 获取指向该分配的 `Weak` 指针的数量的近似值。
    ///
    /// 如果 `self` 是使用 [`Weak::new`] 创建的，或者如果没有剩余的强指针，这将返回 0.
    ///
    /// # Accuracy
    ///
    /// 由于实现细节，当其他线程正在操作任何指向相同分配的 `Arc` 或 `Weak` 时，返回值可以在任一方向上关闭 1。
    ///
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "weak_counts", since = "1.41.0")]
    pub fn weak_count(&self) -> usize {
        self.inner()
            .map(|inner| {
                let weak = inner.weak.load(Acquire);
                let strong = inner.strong.load(Acquire);
                if strong == 0 {
                    0
                } else {
                    // 由于我们在读取弱引用计数后观察到至少有一个强指针，因此我们知道在观察弱引用计数时隐含的弱引用 (在任何强引用活着时都存在) 仍然存在，因此可以安全地减去它。
                    //
                    //
                    //
                    //
                    weak - 1
                }
            })
            .unwrap_or(0)
    }

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

    /// 如果两个 `Weak` 指向与 [`ptr::eq`] 类似的相同分配，或者两者都不指向任何分配 (因为它们是使用 `Weak::new()` 创建的)，则返回 `true`。
    /// 比较 `dyn Trait` 指针时的注意事项，请参见 [that function][`ptr::eq`]。
    ///
    /// # Notes
    ///
    /// 由于这将比较指针，这意味着 `Weak::new()` 将彼此相等，即使它们不指向任何分配。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let first_rc = Arc::new(5);
    /// let first = Arc::downgrade(&first_rc);
    /// let second = Arc::downgrade(&first_rc);
    ///
    /// assert!(first.ptr_eq(&second));
    ///
    /// let third_rc = Arc::new(5);
    /// let third = Arc::downgrade(&third_rc);
    ///
    /// assert!(!first.ptr_eq(&third));
    /// ```
    ///
    /// 比较 `Weak::new`。
    ///
    /// ```
    /// use std::sync::{Arc, Weak};
    ///
    /// let first = Weak::new();
    /// let second = Weak::new();
    /// assert!(first.ptr_eq(&second));
    ///
    /// let third_rc = Arc::new(());
    /// let third = Arc::downgrade(&third_rc);
    /// assert!(!first.ptr_eq(&third));
    /// ```
    ///
    /// [`ptr::eq`]: core::ptr::eq "ptr::eq"
    ///
    ///
    #[inline]
    #[must_use]
    #[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 = "arc_weak", since = "1.4.0")]
impl<T: ?Sized> Clone for Weak<T> {
    /// 克隆 `Weak` 指针，该指针指向相同的分配。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::{Arc, Weak};
    ///
    /// let weak_five = Arc::downgrade(&Arc::new(5));
    ///
    /// let _ = Weak::clone(&weak_five);
    /// ```
    #[inline]
    fn clone(&self) -> Weak<T> {
        let inner = if let Some(inner) = self.inner() {
            inner
        } else {
            return Weak { ptr: self.ptr };
        };
        // 请参阅 Arc::clone() 中的注释，以了解放宽此限制的原因。
        // 这可以使用 fetch_add (忽略锁定)，因为弱引用计数仅在存在 *no 其他* 弱指针的地方被锁定。
        //
        // (因此，在这种情况下，我们无法运行此代码)。
        let old_size = inner.weak.fetch_add(1, Relaxed);

        // 有关为何执行此操作 (对于 mem::forget)，请参见 Arc::clone () 中的注释。
        if old_size > MAX_REFCOUNT {
            abort();
        }

        Weak { ptr: self.ptr }
    }
}

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

#[stable(feature = "arc_weak", since = "1.4.0")]
unsafe impl<#[may_dangle] T: ?Sized> Drop for Weak<T> {
    /// 丢弃 `Weak` 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::{Arc, Weak};
    ///
    /// struct Foo;
    ///
    /// impl Drop for Foo {
    ///     fn drop(&mut self) {
    ///         println!("dropped!");
    ///     }
    /// }
    ///
    /// let foo = Arc::new(Foo);
    /// let weak_foo = Arc::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) {
        // 如果我们发现自己是最后一个弱指针，那么它就该完全释放数据了。参见 Arc::drop () 中有关内存顺序的讨论。
        //
        // 这里没有必要检查锁定状态，因为弱引用计数只能在恰好有一个弱引用的情况下才被锁定，这意味着丢弃只能随后在剩余的弱引用上运行，这只能在释放锁定之后发生。
        //
        //
        //
        //
        //
        let inner = if let Some(inner) = self.inner() { inner } else { return };

        if inner.weak.fetch_sub(1, Release) == 1 {
            acquire!(inner.weak);
            unsafe { Global.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())) }
        }
    }
}

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

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

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

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

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

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

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

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

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

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

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

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + fmt::Display> fmt::Display for Arc<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 Arc<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 Arc<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 = "rust1", since = "1.0.0")]
impl<T: Default> Default for Arc<T> {
    /// 用 `T` 的 `Default` 值创建一个新的 `Arc<T>`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let x: Arc<i32> = Default::default();
    /// assert_eq!(*x, 0);
    /// ```
    fn default() -> Arc<T> {
        Arc::new(Default::default())
    }
}

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

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "from_for_ptrs", since = "1.6.0")]
impl<T> From<T> for Arc<T> {
    /// 将 `T` 转换为 `Arc<T>`
    ///
    /// 转换将值移动到新分配的 `Arc` 中。
    /// 相当于调用 `Arc::new(t)`。
    ///
    /// # Example
    ///
    /// ```rust
    /// # use std::sync::Arc;
    /// let x = 5;
    /// let arc = Arc::new(5);
    ///
    /// assert_eq!(Arc::from(x), arc);
    /// ```
    fn from(t: T) -> Self {
        Arc::new(t)
    }
}

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

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

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

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

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "shared_from_slice", since = "1.21.0")]
impl<T> From<Vec<T>> for Arc<[T]> {
    /// 分配一个引用计数的切片，并将 `v` 的项移入其中。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::sync::Arc;
    /// let unique: Vec<i32> = vec![1, 2, 3];
    /// let shared: Arc<[i32]> = Arc::from(unique);
    /// assert_eq!(&[1, 2, 3], &shared[..]);
    /// ```
    #[inline]
    fn from(mut v: Vec<T>) -> Arc<[T]> {
        unsafe {
            let rc = Arc::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 Arc<B>
where
    B: ToOwned + ?Sized,
    Arc<B>: From<&'a B> + From<B::Owned>,
{
    /// 通过复制其内容，从写时克隆指针创建一个原子引用计数指针。
    ///
    ///
    /// # Example
    ///
    /// ```rust
    /// # use std::sync::Arc;
    /// # use std::borrow::Cow;
    /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant");
    /// let shared: Arc<str> = Arc::from(cow);
    /// assert_eq!("eggplant", &shared[..]);
    /// ```
    #[inline]
    fn from(cow: Cow<'a, B>) -> Arc<B> {
        match cow {
            Cow::Borrowed(s) => Arc::from(s),
            Cow::Owned(s) => Arc::from(s),
        }
    }
}

#[stable(feature = "shared_from_str", since = "1.62.0")]
impl From<Arc<str>> for Arc<[u8]> {
    /// 将原子引用计数的字符串切片转换为字节切片。
    ///
    /// # Example
    ///
    /// ```
    /// # use std::sync::Arc;
    /// let string: Arc<str> = Arc::from("eggplant");
    /// let bytes: Arc<[u8]> = Arc::from(string);
    /// assert_eq!("eggplant".as_bytes(), bytes.as_ref());
    /// ```
    #[inline]
    fn from(rc: Arc<str>) -> Self {
        // SAFETY: `str` 与 `[u8]` 具有相同的布局。
        unsafe { Arc::from_raw(Arc::into_raw(rc) as *const [u8]) }
    }
}

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

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

/// 专门的 trait 用于收集到 `Arc<[T]>` 中。
trait ToArcSlice<T>: Iterator<Item = T> + Sized {
    fn to_arc_slice(self) -> Arc<[T]>;
}

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

#[cfg(not(no_global_oom_handling))]
impl<T, I: iter::TrustedLen<Item = T>> ToArcSlice<T> for I {
    fn to_arc_slice(self) -> Arc<[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: 我们需要确保迭代器有一个精确的长度，并且我们有。
                Arc::from_iter_exact(self, low)
            }
        } else {
            // TrustedLen 契约保证 `upper_bound == None` 意味着迭代器长度超过 `usize::MAX`。
            //
            // 默认实现将收集到一个 vec 中，这将是 panic。
            // 因此，我们立即在此处 panic 而不调用 `Vec` 代码。
            panic!("capacity overflow");
        }
    }
}

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

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

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

/// 获取指针后面有效载荷的 `ArcInner` 内的偏移量。
///
/// # Safety
///
/// 指针必须指向 T 的先前有效实例 (并具有有效的元数据)，但是允许丢弃 T。
///
unsafe fn data_offset<T: ?Sized>(ptr: *const T) -> usize {
    // 将未定义大小的值与 ArcInner 的末端对齐。
    // 由于 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) -> usize {
    let layout = Layout::new::<ArcInner<()>>();
    layout.size() + layout.padding_needed_for(align)
}

#[stable(feature = "arc_error", since = "1.52.0")]
impl<T: core::error::Error + ?Sized> core::error::Error for Arc<T> {
    #[allow(deprecated, deprecated_in_future)]
    fn description(&self) -> &str {
        core::error::Error::description(&**self)
    }

    #[allow(deprecated)]
    fn cause(&self) -> Option<&dyn core::error::Error> {
        core::error::Error::cause(&**self)
    }

    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        core::error::Error::source(&**self)
    }

    fn provide<'a>(&'a self, req: &mut core::any::Demand<'a>) {
        core::error::Error::provide(&**self, req);
    }
}