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

//! 线程安全的引用计数指针。
//!
//! 有关更多详细信息，请参见 [`Arc<T>`][Arc] 文档。

use core::any::Any;
use core::borrow;
use core::cmp::Ordering;
use core::convert::{From, TryFrom};
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, Unpin, 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::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, SeqCst};

#[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` 引用处终止程序 (尽管不一定)。
///
const MAX_REFCOUNT: usize = (isize::MAX) as usize;

#[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] 类型之一。
///
/// ## 线程安全
///
/// 与 [`Rc<T>`] 不同，`Arc<T>` 对其引用计数使用原子运算。这意味着它是线程安全的。缺点是原子操作比普通的内存访问更昂贵。如果您不共享线程之间的引用计数分配，请考虑使用 [`Rc<T>`] 来降低开销。
/// [`Rc<T>`] 是安全的默认设置，因为编译器将捕获在线程之间发送 [`Rc<T>`] 的任何尝试。
/// 但是，磁带库可能选择 `Arc<T>`，以便为磁带库使用者提供更大的灵活性。
///
/// `Arc<T>` 只要 `T` 实现 [`Send`] 和 [`Sync`]，就将实现 [`Send`] 和 [`Sync`]。
/// 为什么不能在 `Arc<T>` 中放置非线程安全类型 `T` 使其成为线程安全的? 起初这可能有点违反直觉: 毕竟，`Arc<T>` 线程安全性不是重点吗? 关键在于: `Arc<T>` 使具有同一数据的多个所有权成为线程安全的，但并未为其数据增加线程安全。
///
/// 考虑 `Arc<`[`RefCell<T>`]`>`。
/// [`RefCell<T>`] 不是 [`Sync`]，并且如果 `Arc<T>` 始终是 [`Send`]，那么 `Arc<`[`RefCell<T>`]`>` 也是如此。
/// 但是然后我们会遇到一个问题:
/// [`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 都是指向相同内存位置的弧
/// ```
///
/// ## `Deref` behavior
///
/// `Arc<T>` 自动取消对 `T` 的引用 (通过 [`Deref`][deref] trait)，因此您可以在 `Arc<T>` 类型的值上调用 `T` 的方法。为了避免与 T 方法的名称冲突，`Arc<T>` 本身的方法是关联函数，使用 [fully qualified syntax] 进行调用:
///
/// ```
/// use std::sync::Arc;
///
/// let my_arc = Arc::new(());
/// 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
/// [`Send`]: core::marker::Send
/// [`Sync`]: core::marker::Sync
/// [deref]: core::ops::Deref
/// [downgrade]: Arc::downgrade
/// [upgrade]: Weak::upgrade
/// [`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
///
/// ```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> {}

#[unstable(feature = "coerce_unsized", issue = "27732")]
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> {
    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`] 来访问该分配，该指针返回 [`Option`]`<`[`Arc`]`<T>>`。
///
/// 由于 `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 = "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> {}

#[stable(feature = "arc_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)")
    }
}

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

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

    data: T,
}

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 ArcInner {
            strong: atomic::AtomicUsize::new(1),
            weak: atomic::AtomicUsize::new(1),
            data,
        };
        Self::from_inner(Box::leak(x).into())
    }

    /// 使用对自身的弱引用创建一个新的 `Arc<T>`。
    /// 在此函数返回之前尝试升级弱引用将得到 `None` 值。
    /// 但是，弱引用可以自由克隆并存储以备后用。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(arc_new_cyclic)]
    /// #![allow(dead_code)]
    ///
    /// use std::sync::{Arc, Weak};
    ///
    /// struct Foo {
    ///     me: Weak<Foo>,
    /// }
    ///
    /// let foo = Arc::new_cyclic(|me| Foo {
    ///     me: me.clone(),
    /// });
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[unstable(feature = "arc_new_cyclic", issue = "75861")]
    pub fn new_cyclic(data_fn: impl FnOnce(&Weak<T>) -> T) -> Arc<T> {
        // 在未初始化状态下用一个弱引用建造内部。
        //
        let uninit_ptr: NonNull<_> = Box::leak(box 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);

        // 现在我们可以正确地初始化内部值，并将我们的弱引用变成强引用。
        //
        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");
        }

        let strong = 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();
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Arc::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() -> 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]: ../../std/mem/union.MaybeUninit.html#method.zeroed
    ///
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    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")]
    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,
        })?;
        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()?;
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Arc::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<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` 相同。
    ///
    ///
    /// 即使存在突出的弱引用，此操作也将成功。
    ///
    /// # 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)
        }
    }
}

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 values = unsafe {
    ///     // 延迟初始化:
    ///     Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
    ///     Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
    ///     Arc::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) -> 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]: ../../std/mem/union.MaybeUninit.html#method.zeroed
    ///
    #[cfg(not(no_global_oom_handling))]
    #[unstable(feature = "new_uninit", issue = "63291")]
    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`]: ../../std/mem/union.MaybeUninit.html#method.assume_init
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let mut five = Arc::<u32>::new_uninit();
    ///
    /// let five = unsafe {
    ///     // 延迟初始化:
    ///     Arc::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) -> Arc<T> {
        Arc::from_inner(mem::ManuallyDrop::new(self).ptr.cast())
    }
}

impl<T> Arc<[mem::MaybeUninit<T>]> {
    /// 转换为 `Arc<[T]>`。
    ///
    /// # Safety
    ///
    /// 与 [`MaybeUninit::assume_init`] 一样，由调用方负责确保内部值确实处于初始化状态。
    ///
    /// 在内容尚未完全初始化时调用此方法会立即导致未定义的行为。
    ///
    /// [`MaybeUninit::assume_init`]: ../../std/mem/union.MaybeUninit.html#method.assume_init
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(new_uninit)]
    /// #![feature(get_mut_unchecked)]
    ///
    /// use std::sync::Arc;
    ///
    /// let mut values = Arc::<[u32]>::new_uninit_slice(3);
    ///
    /// let values = unsafe {
    ///     // 延迟初始化:
    ///     Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
    ///     Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
    ///     Arc::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) -> 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");
    /// ```
    #[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");
    /// ```
    #[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 出处所必需的，例如
        // `get_mut` 通过 `from_raw` 恢复 Rc 后，可以通过指针写入。
        //
        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 as *mut ArcInner<T>).set_ptr_value((ptr as *mut u8).offset(-offset));

            Self::from_ptr(arc_ptr)
        }
    }

    /// 创建一个指向该分配的新 [`Weak`] 指针。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::Arc;
    ///
    /// let five = Arc::new(5);
    ///
    /// let weak_five = Arc::downgrade(&five);
    /// ```
    #[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;
            }

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

            // 与 Clone() 不同，我们需要将其作为 Acquire 读取，以与来自 `is_unique` 的写入同步，以便该写入之前的事件在此读取之前发生。
            //
            //
            match this.inner().weak.compare_exchange_weak(cur, cur + 1, Acquire, Relaxed) {
                Ok(_) => {
                    // 确保我们不会产生悬空的弱点
                    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]
    #[stable(feature = "arc_counts", since = "1.15.0")]
    pub fn weak_count(this: &Self) -> usize {
        let cnt = this.inner().weak.load(SeqCst);
        // 如果弱引用计数当前处于锁定状态，则在进行锁定之前，该计数的值为 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]
    #[stable(feature = "arc_counts", since = "1.15.0")]
    pub fn strong_count(this: &Self) -> usize {
        this.inner().strong.load(SeqCst)
    }

    /// 与提供的指针关联的 `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) {
        // 保留弧，但不要通过包裹在 ManuallyDrop 中来接触引用计数
        let arc = unsafe { mem::ManuallyDrop::new(Arc::<T>::from_raw(ptr)) };
        // 现在增加 refcount，但也不要丢弃新的 refcount
        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 { mem::drop(Arc::from_raw(ptr)) };
    }

    #[inline]
    fn inner(&self) -> &ArcInner<T> {
        // 这种不安全的做法是可以的，因为当此弧保持活动状态时，我们可以保证内部指针有效。
        // 此外，我们知道 `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 });
    }

    #[inline]
    #[stable(feature = "ptr_eq", since = "1.17.0")]
    /// 如果两个 Arc 指向相同的分配 (类似于 [`ptr::eq`])，则返回 `true`。
    ///
    ///
    /// # 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
    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> {
        // 使用给定的值布局计算布局。
        // 以前，在表达式 `&*(ptr as* const ArcInner<T>)` 上计算布局，但是这会产生未对齐的引用 (请参见 #54908)。
        //
        //
        let layout = Layout::new::<ArcInner<()>>().extend(value_layout).unwrap().0.pad_to_align();
        unsafe {
            Arc::try_allocate_for_layout(value_layout, allocate, mem_to_arcinner)
                .unwrap_or_else(|_| handle_alloc_error(layout))
        }
    }

    /// 为 `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> {
        // 使用给定的值布局计算布局。
        // 以前，在表达式 `&*(ptr as* const ArcInner<T>)` 上计算布局，但是这会产生未对齐的引用 (请参见 #54908)。
        //
        //
        let layout = Layout::new::<ArcInner<()>>().extend(value_layout).unwrap().0.pad_to_align();

        let ptr = allocate(layout)?;

        // 初始化 ArcInner
        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));
        }

        Ok(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| (ptr as *mut ArcInner<T>).set_ptr_value(mem) as *mut 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 iter::Iterator<Item = T>, len: usize) -> Arc<[T]> {
        // Panic 在克隆 T 元素时进行保护。
        // 如果出现 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 documentation][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::forgeting Arcs 了，我们需要提防大量引用。
        // 如果我们不这样做，那么计数可能会溢出，并且用户将免费使用。
        // 我们假设没有 ~2 十亿个线程同时增加引用计数，所以我们狂喜地饱和到 `isize::MAX`。
        //
        // 在任何实际程序中都不会采用此分支。
        //
        // 我们终止是因为这样的程序简直令人难以置信的退化，并且我们不在乎支持它。
        //
        //
        if old_size > MAX_REFCOUNT {
            abort();
        }

        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` 或 [`Weak`] 指针指向同一分配，则 `make_mut` 将创建一个新分配，并在内部值上调用 [`clone`][clone] 以确保唯一的所有权。
    /// 这也称为写时克隆。
    ///
    /// 请注意，这与 [`Rc::make_mut`] 的行为不同，后者取消关联所有剩余的 `Weak` 指针。
    ///
    /// 另请参见 [`get_mut`][get_mut]，它将失败而不是克隆。
    ///
    /// [clone]: Clone::clone
    /// [get_mut]: Arc::get_mut
    /// [`Rc::make_mut`]: super::rc::Rc::make_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);
    /// ```
    ///
    ///
    #[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 {
            // 上面的内容足以满足需要，因为这从根本上来说是一种优化: 我们一直在争夺被丢弃的弱指针。
            // 最坏的情况是，我们最终不必要地分配了新的 Arc。
            //

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

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

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

            // 只能窃取数据，剩下的就是弱点
            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) }
    }
}

impl<T: ?Sized> Arc<T> {
    /// 如果没有其他 `Arc` 或 [`Weak`] 指向相同分配的指针，则返回给定 `Arc` 的可变引用。
    ///
    ///
    /// 否则返回 [`None`]，因为更改共享值并不安全。
    ///
    /// 另请参见 [`make_mut`][make_mut]，当存在其他指针时，它将 [`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`] 指针。
    ///
    /// 如果不存在这样的指针 (例如紧接在 `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");
    /// ```
    ///
    ///
    #[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> {
    #[inline]
    #[stable(feature = "rc_downcast", since = "1.29.0")]
    /// 尝试将 `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));
    /// ```
    pub fn downcast<T>(self) -> Result<Arc<T>, Self>
    where
        T: Any + Send + Sync + 'static,
    {
        if (*self).is::<T>() {
            let ptr = self.ptr.cast::<ArcInner<T>>();
            mem::forget(self);
            Ok(Arc::from_inner(ptr))
        } else {
            Err(self)
        }
    }
}

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")]
    pub fn new() -> Weak<T> {
        Weak { ptr: NonNull::new(usize::MAX as *mut ArcInner<T>).expect("MAX is not 0") }
    }
}

/// 帮助程序类型，允许访问引用计数而无需对数据字段进行任何声明。
///
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
    #[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，则该指针是可解引用的。
            // 有效载荷可以在此时被丢弃，所以我们必须持有 provenance，因此请使用裸指针操作。
            //
            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
    ///
    ///
    #[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
    /// [`forget`]: std::mem::forget
    ///
    ///
    ///
    #[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 ArcInner<T>
        } else {
            // 否则，我们保证指针来自无悬挂的弱。
            // SAFETY: data_offset 可以安全调用，因为 ptr 引用了一个真实的 (可能已丢弃) 的 T。
            let offset = unsafe { data_offset(ptr) };
            // 因此，我们反转偏移量以获得整个 RcBox。
            // SAFETY: 指针源自弱点，因此此偏移量是安全的。
            unsafe { (ptr as *mut ArcInner<T>).set_ptr_value((ptr as *mut u8).offset(-offset)) }
        };

        // 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());
    /// ```
    #[stable(feature = "arc_weak", since = "1.4.0")]
    pub fn upgrade(&self) -> Option<Arc<T>> {
        // 我们使用 CAS 循环而不是 fetch_add 来增加强引用计数，因为此函数绝不应该将引用计数从零变为一。
        //
        //
        let inner = self.inner()?;

        // 放宽负载，因为我们可以观察到的任何写入 0 都使该字段处于永久零状态 (因此 "stale" 读取为 0 很好)，并且可以通过下面的 CAS 确认其他任何值。
        //
        //
        //
        let mut n = inner.strong.load(Relaxed);

        loop {
            if n == 0 {
                return None;
            }

            // 请参见 `Arc::clone` 中的注释以了解执行此操作的原因 (对于 `mem::forget`)。
            if n > MAX_REFCOUNT {
                abort();
            }

            // 对于失败案例，放宽是可以的，因为我们对新状态没有任何期望。
            // 如果可以在创建 `Weak` 引用后初始化内部值，则成功案例需要与 `Arc::new_cyclic` 同步进行获取。
            // 在这种情况下，我们希望观察到完全初始化的值。
            //
            match inner.strong.compare_exchange_weak(n, n + 1, Acquire, Relaxed) {
                Ok(_) => return Some(Arc::from_inner(self.ptr)), // 在上面检查为空
                Err(old) => n = old,
            }
        }
    }

    /// 获取指向该分配的强 (`Arc`) 指针的数量。
    ///
    /// 如果 `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.load(SeqCst) } else { 0 }
    }

    /// 获取指向该分配的 `Weak` 指针的数量的近似值。
    ///
    /// 如果 `self` 是使用 [`Weak::new`] 创建的，或者没有剩余的强指针，则它将返回 0。
    ///
    /// # Accuracy
    ///
    /// 由于实现细节，当其他线程操纵指向同一分配的任何 `Arc` 或 `Weak` 时，返回的值可以在任一方向上都减 1。
    ///
    ///
    ///
    ///
    #[stable(feature = "weak_counts", since = "1.41.0")]
    pub fn weak_count(&self) -> usize {
        self.inner()
            .map(|inner| {
                let weak = inner.weak.load(SeqCst);
                let strong = inner.strong.load(SeqCst);
                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`。
    ///
    ///
    /// # 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
    ///
    ///
    #[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 = "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 arc = Arc::copy_from_slice(&v);

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

            arc
        }
    }
}

#[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 = "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> iter::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: iter::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) -> isize {
    // 将未定义大小的值与 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) -> isize {
    let layout = Layout::new::<ArcInner<()>>();
    (layout.size() + layout.padding_needed_for(align)) as isize
}