//! 多生产者，单消费者 FIFO 队列通信原语。
//!
//! 该模块通过通道提供基于消息的通信，具体定义为以下三种类型:
//!
//! * [`Sender`]
//! * [`SyncSender`]
//! * [`Receiver`]
//!
//! [`Sender`] 或 [`SyncSender`] 用于将数据发送到 [`Receiver`]。
//! 两个发送者都是可克隆的 (multi-producer)，因此许多线程可以同时发送到一个接收者 (single-consumer)。
//!
//! 这些通道有两种口味:
//!
//! 1. 异步，无限缓冲的通道。
//! [`channel`] 函数将返回 `(Sender, Receiver)` 元组，其中所有发送都是异步的 (它们从不阻塞)。
//! 通道在概念上具有无限的缓冲区。
//!
//! 2. 同步的有界通道。
//! [`sync_channel`] 函数将返回 `(SyncSender, Receiver)` 元组，其中待处理消息的存储是固定大小的预分配缓冲区。
//! 所有的发送都将被阻塞，直到有可用的缓冲区空间。
//! 请注意，允许的界限为 0，从而使通道成为 "rendezvous" 通道，每个发送者在该通道上原子地将消息传递给接收者。
//!
//! [`send`]: Sender::send
//!
//! ## Disconnection
//!
//! 通道上的发送和接收操作都将返回 [`Result`]，指示该操作是否成功。
//! 不成功的操作通常通过将其丢弃在相应线程中来指示具有 "hung up" 的通道的另一半。
//!
//! 释放通道的一半后，大多数操作将不再继续进行，因此将返回 [`Err`]。
//! 许多应用程序将继续对该模块返回的结果进行 [`unwrap`] 处理，如果一个线程意外死亡，则会导致线程之间传播失败。
//!
//!
//! [`unwrap`]: Result::unwrap
//!
//! # Examples
//!
//! 简单用法:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::channel;
//!
//! // 创建一个简单的流媒体通道
//! let (tx, rx) = channel();
//! thread::spawn(move|| {
//!     tx.send(10).unwrap();
//! });
//! assert_eq!(rx.recv().unwrap(), 10);
//! ```
//!
//! 共享用法:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::channel;
//!
//! // 创建一个可以从许多线程一起发送的共享通道，其中 tx 是发送一半 (用于传输的 tx)，rx 是接收一半 (用于接收的 rx)。
//! //
//! //
//! let (tx, rx) = channel();
//! for i in 0..10 {
//!     let tx = tx.clone();
//!     thread::spawn(move|| {
//!         tx.send(i).unwrap();
//!     });
//! }
//!
//! for _ in 0..10 {
//!     let j = rx.recv().unwrap();
//!     assert!(0 <= j && j < 10);
//! }
//! ```
//!
//! 传播 panics:
//!
//! ```
//! use std::sync::mpsc::channel;
//!
//! // 调用 recv() 将返回错误，因为通道已挂起 (或已释放)
//! //
//! let (tx, rx) = channel::<i32>();
//! drop(tx);
//! assert!(rx.recv().is_err());
//! ```
//!
//! 同步通道:
//!
//! ```
//! use std::thread;
//! use std::sync::mpsc::sync_channel;
//!
//! let (tx, rx) = sync_channel::<i32>(0);
//! thread::spawn(move|| {
//!     // 这将等待父线程开始接收
//!     tx.send(53).unwrap();
//! });
//! rx.recv().unwrap();
//! ```
//!
//! 无限接收循环:
//!
//! ```
//! use std::sync::mpsc::sync_channel;
//! use std::thread;
//!
//! let (tx, rx) = sync_channel(3);
//!
//! for _ in 0..3 {
//!     // 这里没有线程和克隆也是一样的，因为仍然会剩下一个 `tx`。
//!     //
//!     let tx = tx.clone();
//!     // 克隆的 tx 丢弃在线程中
//!     thread::spawn(move || tx.send("ok").unwrap());
//! }
//!
//! // 删除最后一个发送者停止 `rx` 等待消息。
//! // 如果我们将其注释掉，程序将无法完成。
//! // 所有需要为 `rx` 排除 `tx` 才能拥有 `Err`。
//! drop(tx);
//!
//! // 无限接收者等待所有发送者完成。
//! while let Ok(msg) = rx.recv() {
//!     println!("{}", msg);
//! }
//!
//! println!("completed");
//! ```
//!
//!
//!
//!
//!
//!
//!
//!

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

#[cfg(all(test, not(target_os = "emscripten")))]
mod tests;

#[cfg(all(test, not(target_os = "emscripten")))]
mod sync_tests;

// Rust 的通道实现的工作方式的描述
//
// 通道应该是 Rust 中使用的所有其他并发原语的基本构建块。因此，通道类型需要高度优化，灵活并且足够广泛以在任何地方使用。
//
// 所有通道的实现选择都将基于无锁数据结构。因此，通道本身也是无锁数据结构。
// 与使用无锁代码一样，这是一个非常 "here be dragons" 的领域，尤其是因为我不知道任何有关这些类型的通道的学术论文都花了很多篇幅。
//
// ## 通道的味道
//
// 从该库的使用者的角度来看，只有一种味道的通道。此通道可以用作流，并可以克隆以允许多个发送者。
// 然而，在引擎盖下，实际上有三种口味的通道在起作用。
//
// * Flavor::Oneshots - 这些通道针对单发送用例进行了高度优化。它们包含尽可能少的原子，并且涉及一个且恰好是一个分配。
// * 流 - 这些通道针对非共享用例进行了优化。他们使用了一个更适合此用例的不同并发队列。通道的这种风格的初始分配未优化。
// * 共享 - 这是此模块提供的最通用的通道形式，即具有多个发送者的通道。这种类型已尽可能地进行了优化，但是前面提到的两种类型在其用例方面要快得多。
//
// ## 并发队列
//
// Rust 的 Sender/Receiver 类型的基本思想是 send() 永远不会阻塞，但 recv() 显然会阻塞。这意味着在后台必须有一些共享和并发队列保存所有实际数据。
//
// 对于两种通道，还使用两种队列。
// 我们选择使用知名作者 (简称为 SPSC 和 MPSC) 的队列 (单生产者，单一消费者，多生产者，单一消费者)。
// SPSC 队列用于流，而 MPSC 队列用于共享通道。
//
// ### SPSC 优化
//
// 在线找到的 SPSC 队列实质上是节点的链表，其中一半节点是 "queue of data"，另一半节点是未使用节点的缓存。
// 使用未使用的节点，这样就不需要在每个 push() 上进行分配，并且不需要在每个 pop() 上进行分配。
//
// 然而，正如在网上发现的那样，节点的缓存是无限大的。这意味着，如果某个通道在其生命周期的某一点上有 50k 项，那么该队列将始终具有 50k 项的容量。
// 我认为这是对实现的不必要限制，因此我更改了队列以有选择地对缓存大小进行限制。
//
// 默认情况下，流将具有无限制的 SPSC 队列，且缓存大小较小。
// 希望缓存仍然足够大，可以进行非常快速的 send() 操作，而又不要太大，以至于数以百万计的通道可以一次共存。
//
// ### MPSC 优化
//
// 目前，MPSC 队列尚未优化。像 SPSC 队列一样，它使用引擎盖下的链表来获取其无限制的内容，但是我并没有花太多精力来使节点的缓存类似于 SPSC 队列。
//
// 现在，我认为这是 "ok"，因为共享通道不是最常见的类型，但是不久之后，我们不妨重新访问此队列选择，并确定另一个用于共享通道的后端存储的候选对象。
//
// ## 实现概述
//
// 既然使用的并发队列有一些背景知识，那么有必要进一步详细介绍通道本身。send/recv 的基本伪代码为:
//
//      send(t)                             recv() queue.push(t)                       return if queue.pop() if increment() == -1                deschedule { wakeup()                            if decrement() > 0
//                                                cancel_deschedule()
//                                            }
//                                            queue.pop()
//
// 如前所述，此实现中没有锁，仅使用原子指令。
//
// ### 内部原子计数器
//
// 每个通道都有一个共享的计数器，每个通道都有一个计数器，以跟踪队列的大小。该计数器用于接收方终止调度，并知道何时在发送方唤醒。
//
// 从伪代码中可以看出，发送者将增加该计数，接收者将减少该计数。其背后的理论是，如果发送者看到
// -1 计数，它将唤醒接收者，并且如果接收者看到 1 + 计数，则不需要阻塞。
//
// recv() 方法从 pop() 开始调用，如果成功，则需要减少计数。这是一个至关重要的实现细节，此减量不会 * 发生在共享计数器上。
// 如果是这样，那么在没有等待接收者的情况下，计数器可能会变得非常负数，在这种情况下，发送者将不得不确定何时真正适合唤醒接收者。
//
//
// 取而代之的是，"steal count" 被分开跟踪 (不是原子地，因为它仅由接收者使用)，然后在调度时将 decrement() 调用将最近的所有窃取都归为一个大的递减。
//
// 这意味着如果发送方看到 -1 计数，那么肯定有一个等待者在等!
//
// ## 原生实现
//
// 这些通道的主要目标是在运行时上上下下无缝工作。
// 以前的所有竞争状态都用调度程序表述 (显然，没有运行时就无法使用)。
//
// 目前，通道的原生用法 (在运行时关闭) 将回退到 mutexes/cond 变量上进行 descheduling/atomic 决策。
// 无争用路径仍然是完全无锁的，上面的 "deschedule" 块被互斥锁包围，而 "wakeup" 块涉及获取互斥锁并在条件变量上发出信号。
//
// ## Select
//
// 能够支持通过通道进行选择极大地影响了该设计，选择不仅需要在运行时内部进行，而且还需要在运行时外部进行。
//
// 该实现非常简单。select() 的目标不是返回某些数据，而只是返回哪个通道可以无阻塞地接收数据。
// 该实现实质上是整个阻塞进程，随后在其唤醒后立即进行递增。
// 取消进程涉及一个增量，并交换出 to_wake 来获取要解锁的线程的所有权。
//
// 可悲的是，当前的实现需要多个分配，因此我已经看到 select() 的吞吐量比应该的要差得多。
// 我认为，为了支持更高效的 select()，不需要对这些通道进行任何根本性的更改。
//
// FIXME: Select 现在已删除，因此可以清除这些因素!
//
// # Conclusion
//
// 现在，您已经看到了我发现并尝试解决的所有问题，下面是为您找到更多代码的代码!
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//

use crate::cell::UnsafeCell;
use crate::error;
use crate::fmt;
use crate::mem;
use crate::sync::Arc;
use crate::time::{Duration, Instant};

mod blocking;
mod mpsc_queue;
mod oneshot;
mod shared;
mod spsc_queue;
mod stream;
mod sync;

mod cache_aligned;

/// Rust 的 [`channel`] (或 [`sync_channel`]) 类型的接收一半。
/// 这一半只能由一个线程拥有。
///
/// 可以使用 [`recv`] 检索发送到通道的消息。
///
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send("Hello world!").unwrap();
///     thread::sleep(Duration::from_secs(2)); // 阻塞两秒钟
///     send.send("Delayed for 2 seconds").unwrap();
/// });
///
/// println!("{}", recv.recv().unwrap()); // 立即收到
/// println!("Waiting...");
/// println!("{}", recv.recv().unwrap()); // 2 秒后收到
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Receiver")]
pub struct Receiver<T> {
    inner: UnsafeCell<Flavor<T>>,
}

// 接收者端口可以在任何地方发送，只要它不用于接收不可发送的东西即可。
//
#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for Receiver<T> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Receiver<T> {}

/// [`iter`] 在 [`Receiver`] 上创建的消息上的迭代器。
///
/// 每当调用 [`next`]，等待新消息时，此迭代器将阻塞，并且在相应的通道挂起时，将返回 [`None`]。
///
///
/// [`iter`]: Receiver::iter
/// [`next`]: Iterator::next
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send(1u8).unwrap();
///     send.send(2u8).unwrap();
///     send.send(3u8).unwrap();
/// });
///
/// for x in recv.iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Iter<'a, T: 'a> {
    rx: &'a Receiver<T>,
}

/// 尝试产生 [`try_iter`] 创建的 [`Receiver`] 的所有挂起值的迭代器。
///
/// [`None`] 当没有剩余的待处理值或相应的通道已挂断时，将返回。
///
///
/// 该迭代器永远不会阻塞调用方，以等待数据可用。
/// 相反，它将返回 [`None`]。
///
/// [`try_iter`]: Receiver::try_iter
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (sender, receiver) = channel();
///
/// // 缓冲区什么都没有了
/// assert!(receiver.try_iter().next().is_none());
/// println!("Nothing in the buffer...");
///
/// thread::spawn(move || {
///     sender.send(1).unwrap();
///     sender.send(2).unwrap();
///     sender.send(3).unwrap();
/// });
///
/// println!("Going to sleep...");
/// thread::sleep(Duration::from_secs(2)); // 阻塞两秒钟
///
/// for x in receiver.try_iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
#[stable(feature = "receiver_try_iter", since = "1.15.0")]
#[derive(Debug)]
pub struct TryIter<'a, T: 'a> {
    rx: &'a Receiver<T>,
}

/// [`Receiver`] 上由消息接收者拥有的迭代器，该迭代器由 **接收者::into_iter** 创建。
///
/// 每当调用 [`next`]，等待新消息时，此迭代器将阻塞，如果相应的通道已挂起，则将返回 [`None`]。
///
///
/// [`next`]: Iterator::next
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (send, recv) = channel();
///
/// thread::spawn(move || {
///     send.send(1u8).unwrap();
///     send.send(2u8).unwrap();
///     send.send(3u8).unwrap();
/// });
///
/// for x in recv.into_iter() {
///     println!("Got: {}", x);
/// }
/// ```
///
///
#[stable(feature = "receiver_into_iter", since = "1.1.0")]
#[derive(Debug)]
pub struct IntoIter<T> {
    rx: Receiver<T>,
}

/// Rust 的异步 [`channel`] 类型的发送一半。
/// 这一半只能由一个线程拥有，但可以克隆以发送给其他线程。
///
/// 可以使用 [`send`] 通过此通道发送消息。
///
/// Note: 所有发送者 (原始和克隆) 都需要被接收者去除，以停止阻止接收带有 [`Receiver::recv`] 的消息。
///
///
/// [`send`]: Sender::send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (sender, receiver) = channel();
/// let sender2 = sender.clone();
///
/// // 第一个线程拥有发送者
/// thread::spawn(move || {
///     sender.send(1).unwrap();
/// });
///
/// // 第二个线程拥有 sender2
/// thread::spawn(move || {
///     sender2.send(2).unwrap();
/// });
///
/// let msg = receiver.recv().unwrap();
/// let msg2 = receiver.recv().unwrap();
///
/// assert_eq!(3, msg + msg2);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Sender<T> {
    inner: UnsafeCell<Flavor<T>>,
}

// 只要不用于发送不可发送的东西，发送端口就可以从一个地方发送到另一个地方。
//
#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for Sender<T> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Sender<T> {}

/// Rust 的同步 [`sync_channel`] 类型的发送一半。
///
/// 可以使用 [`send`] 或 [`try_send`] 通过此通道发送消息。
///
/// [`send`] 如果内部缓冲区中没有空间，则将阻塞。
///
/// [`send`]: SyncSender::send
/// [`try_send`]: SyncSender::try_send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// // 创建一个缓冲区大小为 2 的 sync_channel
/// let (sync_sender, receiver) = sync_channel(2);
/// let sync_sender2 = sync_sender.clone();
///
/// // 第一个线程拥有 sync_sender
/// thread::spawn(move || {
///     sync_sender.send(1).unwrap();
///     sync_sender.send(2).unwrap();
/// });
///
/// // 第二个线程拥有 sync_sender2
/// thread::spawn(move || {
///     sync_sender2.send(3).unwrap();
///     // 由于缓冲区已满，线程现在将阻塞
///     println!("Thread unblocked!");
/// });
///
/// let mut msg;
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// // "Thread unblocked!" 现在将打印
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// msg = receiver.recv().unwrap();
///
/// println!("message {} received", msg);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SyncSender<T> {
    inner: Arc<sync::Packet<T>>,
}

#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<T: Send> Send for SyncSender<T> {}

/// X **X** 上的 [`Sender::send`] 或 [`SyncSender::send`] 函数返回错误。
///
/// 仅当通道的接收端断开连接时，发送操作才会失败，这意味着永远无法接收到数据。
/// 错误包含正在作为有效负载发送的数据，因此可以对其进行恢复。
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(PartialEq, Eq, Clone, Copy)]
pub struct SendError<T>(#[stable(feature = "rust1", since = "1.0.0")] pub T);

/// [`Receiver`] 上的 [`recv`] 函数返回错误。
///
/// 仅当 [`channel`] (或 [`sync_channel`]) 的发送半部断开连接时，[`recv`] 操作才会失败，这意味着将再也不会收到任何消息。
///
///
/// [`recv`]: Receiver::recv
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct RecvError;

/// 该枚举是 [`try_recv`] 在调用时无法返回数据的可能原因的列表。
/// [`channel`] 和 [`sync_channel`] 都可能发生这种情况。
///
/// [`try_recv`]: Receiver::try_recv
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum TryRecvError {
    /// 该 **通道** 当前为空，但 **发送器** 尚未断开连接，因此数据可能仍可用。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Empty,

    /// **通道** 的发送一半已断开，并且永远不会再收到任何数据。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Disconnected,
}

/// 该枚举是导致 [`recv_timeout`] 在调用时无法返回数据的可能错误的列表。
/// [`channel`] 和 [`sync_channel`] 都可能发生这种情况。
///
/// [`recv_timeout`]: Receiver::recv_timeout
///
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
pub enum RecvTimeoutError {
    /// 该 **通道** 当前为空，但 **发送器** 尚未断开连接，因此数据可能仍可用。
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    Timeout,
    /// **通道** 的发送一半已断开，并且永远不会再收到任何数据。
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    Disconnected,
}

/// 此枚举是 [`try_send`] 方法可能出现的错误结果的列表。
///
///
/// [`try_send`]: SyncSender::try_send
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(PartialEq, Eq, Clone, Copy)]
pub enum TrySendError<T> {
    /// 无法在 [`sync_channel`] 上发送数据，因为这将要求被调用方块发送数据。
    ///
    ///
    /// 如果这是一个缓冲的通道，则此时缓冲区已满。
    /// 如果这不是缓冲的通道，则没有 [`Receiver`] 可用于获取数据。
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    Full(#[stable(feature = "rust1", since = "1.0.0")] T),

    /// 此 [`sync_channel`] 的接收部分已断开连接，因此无法发送数据。
    /// 在这种情况下，数据将返回给被调用方。
    #[stable(feature = "rust1", since = "1.0.0")]
    Disconnected(#[stable(feature = "rust1", since = "1.0.0")] T),
}

enum Flavor<T> {
    Oneshot(Arc<oneshot::Packet<T>>),
    Stream(Arc<stream::Packet<T>>),
    Shared(Arc<shared::Packet<T>>),
    Sync(Arc<sync::Packet<T>>),
}

#[doc(hidden)]
trait UnsafeFlavor<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>>;
    unsafe fn inner_mut(&self) -> &mut Flavor<T> {
        &mut *self.inner_unsafe().get()
    }
    unsafe fn inner(&self) -> &Flavor<T> {
        &*self.inner_unsafe().get()
    }
}
impl<T> UnsafeFlavor<T> for Sender<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>> {
        &self.inner
    }
}
impl<T> UnsafeFlavor<T> for Receiver<T> {
    fn inner_unsafe(&self) -> &UnsafeCell<Flavor<T>> {
        &self.inner
    }
}

/// 创建一个新的异步通道，返回 sender/receiver 一半。
/// 在 [`Sender`] 上发送的所有数据将以与发送时相同的顺序在 [`Receiver`] 上可用，并且没有 [`send`] 将阻塞调用线程 (此通道具有一个 "infinite buffer"，与 [`sync_channel`] 不同，它将在达到其缓冲区限制后阻塞)。
/// [`recv`] 当至少有一个 [`Sender`] 活着 (包括克隆) 时，将阻塞直到消息可用。
///
/// [`Sender`] 可以多次克隆到 [`send`] 到同一通道，但是仅支持一个 [`Receiver`]。
///
/// 如果在尝试使用 [`Sender`] 进行 [`send`] 时断开 [`Receiver`] 的连接，则 [`send`] 方法将返回 [`SendError`]。同样，如果在尝试 [`recv`] 时断开 [`Sender`] 的连接，则 [`recv`] 方法将返回 [`RecvError`]。
///
/// [`send`]: Sender::send
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```
/// use std::sync::mpsc::channel;
/// use std::thread;
///
/// let (sender, receiver) = channel();
///
/// // Spawn 关闭昂贵的计算
/// thread::spawn(move|| {
/// #   fn expensive_computation() {}
///     sender.send(expensive_computation()).unwrap();
/// });
///
/// // 暂时做一些有用的工作
///
/// // 让我们看看答案是什么
/// println!("{:?}", receiver.recv().unwrap());
/// ```
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
    let a = Arc::new(oneshot::Packet::new());
    (Sender::new(Flavor::Oneshot(a.clone())), Receiver::new(Flavor::Oneshot(a)))
}

/// 创建一个新的同步有界通道。
/// [`SyncSender`] 上发送的所有数据将以与发送相同的顺序在 [`Receiver`] 上可用。
/// 像异步 [`channel`] 一样，[`Receiver`] 将阻塞直到消息可用为止。
/// `sync_channel` 但是，发送者的语义差异很大。
///
/// 该通道具有内部缓冲区，消息将在该缓冲区上排队。
/// `bound` 指定缓冲区大小。
/// 当内部缓冲区已满时，future 将发送 *block*，等待缓冲区打开。
/// 请注意，缓冲区大小为 0 是有效的，在这种情况下，它变为 "rendezvous channel"，其中每个 [`send`] 在与 [`recv`] 配对之前不会返回。
///
/// [`SyncSender`] 可以多次克隆到 [`send`] 到同一通道，但是仅支持一个 [`Receiver`]。
///
/// 与异步通道一样，如果在尝试使用 [`SyncSender`] 进行 [`send`] 时断开 [`Receiver`]，则 [`send`] 方法将返回 [`SendError`]。
///
/// 同样，如果在尝试 [`recv`] 时断开 [`SyncSender`] 的连接，则 [`recv`] 方法将返回 [`RecvError`]。
///
/// [`send`]: SyncSender::send
/// [`recv`]: Receiver::recv
///
/// # Examples
///
/// ```
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// let (sender, receiver) = sync_channel(1);
///
/// // 这立即返回
/// sender.send(1).unwrap();
///
/// thread::spawn(move|| {
///     // 这将阻塞，直到收到上一条消息为止
///     sender.send(2).unwrap();
/// });
///
/// assert_eq!(receiver.recv().unwrap(), 1);
/// assert_eq!(receiver.recv().unwrap(), 2);
/// ```
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn sync_channel<T>(bound: usize) -> (SyncSender<T>, Receiver<T>) {
    let a = Arc::new(sync::Packet::new(bound));
    (SyncSender::new(a.clone()), Receiver::new(Flavor::Sync(a)))
}

////////////////////////////////////////////////////////////////////////////////
// Sender
////////////////////////////////////////////////////////////////////////////////

impl<T> Sender<T> {
    fn new(inner: Flavor<T>) -> Sender<T> {
        Sender { inner: UnsafeCell::new(inner) }
    }

    /// 尝试在此通道上发送值，如果无法发送，则将其返回。
    ///
    /// 当确定通道的另一端尚未挂断时，发送成功。
    /// 不成功的发送将是相应的接收者已被重新分配的发送。
    /// 请注意，返回值 [`Err`] 表示将永远不会接收到数据，但是 [`Ok`] 的返回值 *不是* 意味着将接收到数据。
    ///
    /// 此函数返回 [`Ok`] 之后，相应的接收者有可能立即挂断。
    ///
    /// 此方法永远不会阻塞当前线程。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::mpsc::channel;
    ///
    /// let (tx, rx) = channel();
    ///
    /// // 此发送始终成功
    /// tx.send(1).unwrap();
    ///
    /// // 由于接收者不见了，因此发送失败
    /// drop(rx);
    /// assert_eq!(tx.send(1).unwrap_err().0, 1);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn send(&self, t: T) -> Result<(), SendError<T>> {
        let (new_inner, ret) = match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => {
                if !p.sent() {
                    return p.send(t).map_err(SendError);
                } else {
                    let a = Arc::new(stream::Packet::new());
                    let rx = Receiver::new(Flavor::Stream(a.clone()));
                    match p.upgrade(rx) {
                        oneshot::UpSuccess => {
                            let ret = a.send(t);
                            (a, ret)
                        }
                        oneshot::UpDisconnected => (a, Err(t)),
                        oneshot::UpWoke(token) => {
                            // 此发送不能 panic，因为线程处于睡眠状态 (我们正在查看它)，因此接收者无法消失。
                            //
                            //
                            a.send(t).ok().unwrap();
                            token.signal();
                            (a, Ok(()))
                        }
                    }
                }
            }
            Flavor::Stream(ref p) => return p.send(t).map_err(SendError),
            Flavor::Shared(ref p) => return p.send(t).map_err(SendError),
            Flavor::Sync(..) => unreachable!(),
        };

        unsafe {
            let tmp = Sender::new(Flavor::Stream(new_inner));
            mem::swap(self.inner_mut(), tmp.inner_mut());
        }
        ret.map_err(SendError)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Clone for Sender<T> {
    /// 克隆发送者以发送到其他线程。
    ///
    /// 请注意，请注意发送方的生命周期，因为所有发送方 (包括原始发送方) 都需要丢弃，以便 [`Receiver::recv`] 停止阻塞。
    ///
    ///
    fn clone(&self) -> Sender<T> {
        let packet = match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => {
                let a = Arc::new(shared::Packet::new());
                {
                    let guard = a.postinit_lock();
                    let rx = Receiver::new(Flavor::Shared(a.clone()));
                    let sleeper = match p.upgrade(rx) {
                        oneshot::UpSuccess | oneshot::UpDisconnected => None,
                        oneshot::UpWoke(task) => Some(task),
                    };
                    a.inherit_blocker(sleeper, guard);
                }
                a
            }
            Flavor::Stream(ref p) => {
                let a = Arc::new(shared::Packet::new());
                {
                    let guard = a.postinit_lock();
                    let rx = Receiver::new(Flavor::Shared(a.clone()));
                    let sleeper = match p.upgrade(rx) {
                        stream::UpSuccess | stream::UpDisconnected => None,
                        stream::UpWoke(task) => Some(task),
                    };
                    a.inherit_blocker(sleeper, guard);
                }
                a
            }
            Flavor::Shared(ref p) => {
                p.clone_chan();
                return Sender::new(Flavor::Shared(p.clone()));
            }
            Flavor::Sync(..) => unreachable!(),
        };

        unsafe {
            let tmp = Sender::new(Flavor::Shared(packet.clone()));
            mem::swap(self.inner_mut(), tmp.inner_mut());
        }
        Sender::new(Flavor::Shared(packet))
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for Sender<T> {
    fn drop(&mut self) {
        match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => p.drop_chan(),
            Flavor::Stream(ref p) => p.drop_chan(),
            Flavor::Shared(ref p) => p.drop_chan(),
            Flavor::Sync(..) => unreachable!(),
        }
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for Sender<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Sender").finish_non_exhaustive()
    }
}

////////////////////////////////////////////////////////////////////////////////
// SyncSender
////////////////////////////////////////////////////////////////////////////////

impl<T> SyncSender<T> {
    fn new(inner: Arc<sync::Packet<T>>) -> SyncSender<T> {
        SyncSender { inner }
    }

    /// 在此同步通道上发送一个值。
    ///
    /// 该函数将阻塞，直到内部缓冲区中的空间可用或接收者可以将消息传递给它为止。
    ///
    /// 请注意，如果此通道上有缓冲区，则成功发送并不能保证接收者会看到数据。
    /// 该项可能会排队在内部缓冲区中，以供接收者在以后的时间接收。
    /// 但是，如果缓冲区大小为 0，则通道成为集合通道，并且如果此函数返回成功，则它保证接收者确实已接收到数据。
    ///
    ///
    /// 此函数永远不会 panic，但是如果 [`Receiver`] 已断开连接并且不再能够接收信息，则它可能返回 [`Err`]。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::sync_channel;
    /// use std::thread;
    ///
    /// // 创建一个缓冲区大小为 0 的集合点 sync_channel
    /// let (sync_sender, receiver) = sync_channel(0);
    ///
    /// thread::spawn(move || {
    ///    println!("sending message...");
    ///    sync_sender.send(1).unwrap();
    ///    // 现在线程被阻塞，直到收到消息为止
    ///
    ///    println!("...message received!");
    /// });
    ///
    /// let msg = receiver.recv().unwrap();
    /// assert_eq!(1, msg);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn send(&self, t: T) -> Result<(), SendError<T>> {
        self.inner.send(t).map_err(SendError)
    }

    /// 尝试在此通道上发送值而不会阻塞。
    ///
    /// 此方法不同于 [`send`]，如果通道的缓冲区已满或没有接收者正在等待获取某些数据，则立即返回。
    /// 与 [`send`] 相比，此函数有两种故障情况，而不是一种情况 (一种情况是断开连接，一种情况是完整的缓冲区)。
    ///
    /// 请参见 [`send`]，以获取有关确保此函数成功后接收方是否已接收到数据的说明。
    ///
    /// [`send`]: Self::send
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::sync_channel;
    /// use std::thread;
    ///
    /// // 创建一个缓冲区大小为 1 的 sync_channel
    /// let (sync_sender, receiver) = sync_channel(1);
    /// let sync_sender2 = sync_sender.clone();
    ///
    /// // 第一个线程拥有 sync_sender
    /// thread::spawn(move || {
    ///     sync_sender.send(1).unwrap();
    ///     sync_sender.send(2).unwrap();
    ///     // 线程被阻塞
    /// });
    ///
    /// // 第二个线程拥有 sync_sender2
    /// thread::spawn(move || {
    ///     // 如果缓冲区已满，这将返回错误并且不发送任何消息
    /////
    ///     let _ = sync_sender2.try_send(3);
    /// });
    ///
    /// let mut msg;
    /// msg = receiver.recv().unwrap();
    /// println!("message {} received", msg);
    ///
    /// msg = receiver.recv().unwrap();
    /// println!("message {} received", msg);
    ///
    /// // 第三条消息可能从未发送过
    /// match receiver.try_recv() {
    ///     Ok(msg) => println!("message {} received", msg),
    ///     Err(_) => println!("the third message was never sent"),
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn try_send(&self, t: T) -> Result<(), TrySendError<T>> {
        self.inner.try_send(t)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Clone for SyncSender<T> {
    fn clone(&self) -> SyncSender<T> {
        self.inner.clone_chan();
        SyncSender::new(self.inner.clone())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for SyncSender<T> {
    fn drop(&mut self) {
        self.inner.drop_chan();
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for SyncSender<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SyncSender").finish_non_exhaustive()
    }
}

////////////////////////////////////////////////////////////////////////////////
// Receiver
////////////////////////////////////////////////////////////////////////////////

impl<T> Receiver<T> {
    fn new(inner: Flavor<T>) -> Receiver<T> {
        Receiver { inner: UnsafeCell::new(inner) }
    }

    /// 尝试在不阻塞的情况下在此接收者上返回挂起的值。
    ///
    /// 此方法决不会阻塞调用方，以等待数据可用。
    /// 取而代之的是，它总是立即返回，并可能在通道上保留未决数据。
    ///
    /// 在决定阻塞接收者之前，这对于 "optimistic check" 很有用。
    ///
    /// 与 [`recv`] 相比，此函数有两种故障情况，而不是一种情况 (一种情况是断开连接，一种情况是空缓冲区)。
    ///
    ///
    /// [`recv`]: Self::recv
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::{Receiver, channel};
    ///
    /// let (_, receiver): (_, Receiver<i32>) = channel();
    ///
    /// assert!(receiver.try_recv().is_err());
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn try_recv(&self) -> Result<T, TryRecvError> {
        loop {
            let new_port = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Empty) => return Err(TryRecvError::Empty),
                    Err(oneshot::Disconnected) => return Err(TryRecvError::Disconnected),
                    Err(oneshot::Upgraded(rx)) => rx,
                },
                Flavor::Stream(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(stream::Empty) => return Err(TryRecvError::Empty),
                    Err(stream::Disconnected) => return Err(TryRecvError::Disconnected),
                    Err(stream::Upgraded(rx)) => rx,
                },
                Flavor::Shared(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(shared::Empty) => return Err(TryRecvError::Empty),
                    Err(shared::Disconnected) => return Err(TryRecvError::Disconnected),
                },
                Flavor::Sync(ref p) => match p.try_recv() {
                    Ok(t) => return Ok(t),
                    Err(sync::Empty) => return Err(TryRecvError::Empty),
                    Err(sync::Disconnected) => return Err(TryRecvError::Disconnected),
                },
            };
            unsafe {
                mem::swap(self.inner_mut(), new_port.inner_mut());
            }
        }
    }

    /// 尝试等待此接收者上的值，如果相应的通道已挂起，则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在)，此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`Sender`] (或 [`SyncSender`])，该接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接，或者在此调用阻塞时断开连接，则此调用将唤醒并返回 [`Err`]，以指示该通道上再也不会收到任何消息。
    ///
    /// 但是，由于缓冲了通道，因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::sync::mpsc;
    /// use std::thread;
    ///
    /// let (send, recv) = mpsc::channel();
    /// let handle = thread::spawn(move || {
    ///     send.send(1u8).unwrap();
    /// });
    ///
    /// handle.join().unwrap();
    ///
    /// assert_eq!(Ok(1), recv.recv());
    /// ```
    ///
    /// 缓冲行为:
    ///
    /// ```
    /// use std::sync::mpsc;
    /// use std::thread;
    /// use std::sync::mpsc::RecvError;
    ///
    /// let (send, recv) = mpsc::channel();
    /// let handle = thread::spawn(move || {
    ///     send.send(1u8).unwrap();
    ///     send.send(2).unwrap();
    ///     send.send(3).unwrap();
    ///     drop(send);
    /// });
    ///
    /// // 等待线程加入，因此我们确保发送者已被丢弃
    /// handle.join().unwrap();
    ///
    /// assert_eq!(Ok(1), recv.recv());
    /// assert_eq!(Ok(2), recv.recv());
    /// assert_eq!(Ok(3), recv.recv());
    /// assert_eq!(Err(RecvError), recv.recv());
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn recv(&self) -> Result<T, RecvError> {
        loop {
            let new_port = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Disconnected) => return Err(RecvError),
                    Err(oneshot::Upgraded(rx)) => rx,
                    Err(oneshot::Empty) => unreachable!(),
                },
                Flavor::Stream(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(stream::Disconnected) => return Err(RecvError),
                    Err(stream::Upgraded(rx)) => rx,
                    Err(stream::Empty) => unreachable!(),
                },
                Flavor::Shared(ref p) => match p.recv(None) {
                    Ok(t) => return Ok(t),
                    Err(shared::Disconnected) => return Err(RecvError),
                    Err(shared::Empty) => unreachable!(),
                },
                Flavor::Sync(ref p) => return p.recv(None).map_err(|_| RecvError),
            };
            unsafe {
                mem::swap(self.inner_mut(), new_port.inner_mut());
            }
        }
    }

    /// 尝试等待此接收器上的值，如果相应的通道已挂起，或者等待的时间超过 `timeout`，则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在)，此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`Sender`] (或 [`SyncSender`])，该接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接，或者在此调用阻塞时断开连接，则此调用将唤醒并返回 [`Err`]，以指示该通道上再也不会收到任何消息。
    ///
    /// 但是，由于缓冲了通道，因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # 已知的问题
    ///
    /// 当前存在一个已知问题 (请参见 [`#39364`])，以下示例导致 `recv_timeout` 意外变为 panic:
    ///
    /// ```no_run
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    /// use std::time::Duration;
    ///
    /// let (tx, rx) = channel::<String>();
    ///
    /// thread::spawn(move || {
    ///     let d = Duration::from_millis(10);
    ///     loop {
    ///         println!("recv");
    ///         let _r = rx.recv_timeout(d);
    ///     }
    /// });
    ///
    /// thread::sleep(Duration::from_millis(100));
    /// let _c1 = tx.clone();
    ///
    /// thread::sleep(Duration::from_secs(1));
    /// ```
    ///
    /// [`#39364`]: https://github.com/rust-lang/rust/issues/39364
    ///
    /// # Examples
    ///
    /// 在遇到超时之前成功获得值:
    ///
    /// ```no_run
    /// use std::thread;
    /// use std::time::Duration;
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_timeout(Duration::from_millis(400)),
    ///     Ok('a')
    /// );
    /// ```
    ///
    /// 到达超时时收到错误:
    ///
    /// ```no_run
    /// use std::thread;
    /// use std::time::Duration;
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_millis(800));
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_timeout(Duration::from_millis(400)),
    ///     Err(mpsc::RecvTimeoutError::Timeout)
    /// );
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")]
    pub fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError> {
        // 进行乐观的 try_recv 以避免全通道情况下 Instant::now () 的性能影响。
        //
        match self.try_recv() {
            Ok(result) => Ok(result),
            Err(TryRecvError::Disconnected) => Err(RecvTimeoutError::Disconnected),
            Err(TryRecvError::Empty) => match Instant::now().checked_add(timeout) {
                Some(deadline) => self.recv_deadline(deadline),
                // 到目前为止，在 future 中，它实际上与无限期等待相同。
                None => self.recv().map_err(RecvTimeoutError::from),
            },
        }
    }

    /// 尝试等待此接收器上的值，如果相应的通道已挂起，或者到达 `deadline`，则返回错误。
    ///
    /// 如果没有可用数据，并且有可能发送更多数据，则此函数将始终阻止当前线程。
    /// 将消息发送到相应的 [`Sender`] (或 [`SyncSender`]) 后，此接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接，或者在此调用阻塞时断开连接，则此调用将唤醒并返回 [`Err`]，以指示该通道上再也不会收到任何消息。
    ///
    /// 但是，由于缓冲了通道，因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # Examples
    ///
    /// 在截止日期之前成功获得值:
    ///
    /// ```no_run
    /// #![feature(deadline_api)]
    /// use std::thread;
    /// use std::time::{Duration, Instant};
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_deadline(Instant::now() + Duration::from_millis(400)),
    ///     Ok('a')
    /// );
    /// ```
    ///
    /// 在截止日期前收到错误:
    ///
    /// ```no_run
    /// #![feature(deadline_api)]
    /// use std::thread;
    /// use std::time::{Duration, Instant};
    /// use std::sync::mpsc;
    ///
    /// let (send, recv) = mpsc::channel();
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_millis(800));
    ///     send.send('a').unwrap();
    /// });
    ///
    /// assert_eq!(
    ///     recv.recv_deadline(Instant::now() + Duration::from_millis(400)),
    ///     Err(mpsc::RecvTimeoutError::Timeout)
    /// );
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "deadline_api", issue = "46316")]
    pub fn recv_deadline(&self, deadline: Instant) -> Result<T, RecvTimeoutError> {
        use self::RecvTimeoutError::*;

        loop {
            let port_or_empty = match *unsafe { self.inner() } {
                Flavor::Oneshot(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(oneshot::Disconnected) => return Err(Disconnected),
                    Err(oneshot::Upgraded(rx)) => Some(rx),
                    Err(oneshot::Empty) => None,
                },
                Flavor::Stream(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(stream::Disconnected) => return Err(Disconnected),
                    Err(stream::Upgraded(rx)) => Some(rx),
                    Err(stream::Empty) => None,
                },
                Flavor::Shared(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(shared::Disconnected) => return Err(Disconnected),
                    Err(shared::Empty) => None,
                },
                Flavor::Sync(ref p) => match p.recv(Some(deadline)) {
                    Ok(t) => return Ok(t),
                    Err(sync::Disconnected) => return Err(Disconnected),
                    Err(sync::Empty) => None,
                },
            };

            if let Some(new_port) = port_or_empty {
                unsafe {
                    mem::swap(self.inner_mut(), new_port.inner_mut());
                }
            }

            // 如果我们已经超过了最后期限，并且我们没有数据，请返回超时，否则重试。
            //
            if Instant::now() >= deadline {
                return Err(Timeout);
            }
        }
    }

    /// 返回一个迭代器，该迭代器将阻止等待消息，但不会阻止 [`panic!`]。
    /// 通道挂起时，它将返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    ///
    /// let (send, recv) = channel();
    ///
    /// thread::spawn(move || {
    ///     send.send(1).unwrap();
    ///     send.send(2).unwrap();
    ///     send.send(3).unwrap();
    /// });
    ///
    /// let mut iter = recv.iter();
    /// assert_eq!(iter.next(), Some(1));
    /// assert_eq!(iter.next(), Some(2));
    /// assert_eq!(iter.next(), Some(3));
    /// assert_eq!(iter.next(), None);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn iter(&self) -> Iter<'_, T> {
        Iter { rx: self }
    }

    /// 返回一个迭代器，它将尝试产生所有挂起的值。
    /// 如果没有其他未决值或通道已挂断，它将返回 `None`。
    /// 迭代器永远不会 [`panic!`] 或通过等待值来阻止用户。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::sync::mpsc::channel;
    /// use std::thread;
    /// use std::time::Duration;
    ///
    /// let (sender, receiver) = channel();
    ///
    /// // 缓冲区中还没有任何东西
    /// assert!(receiver.try_iter().next().is_none());
    ///
    /// thread::spawn(move || {
    ///     thread::sleep(Duration::from_secs(1));
    ///     sender.send(1).unwrap();
    ///     sender.send(2).unwrap();
    ///     sender.send(3).unwrap();
    /// });
    ///
    /// // 缓冲区中还没有任何东西
    /// assert!(receiver.try_iter().next().is_none());
    ///
    /// // 阻塞两秒钟
    /// thread::sleep(Duration::from_secs(2));
    ///
    /// let mut iter = receiver.try_iter();
    /// assert_eq!(iter.next(), Some(1));
    /// assert_eq!(iter.next(), Some(2));
    /// assert_eq!(iter.next(), Some(3));
    /// assert_eq!(iter.next(), None);
    /// ```
    ///
    #[stable(feature = "receiver_try_iter", since = "1.15.0")]
    pub fn try_iter(&self) -> TryIter<'_, T> {
        TryIter { rx: self }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T> Iterator for Iter<'a, T> {
    type Item = T;

    fn next(&mut self) -> Option<T> {
        self.rx.recv().ok()
    }
}

#[stable(feature = "receiver_try_iter", since = "1.15.0")]
impl<'a, T> Iterator for TryIter<'a, T> {
    type Item = T;

    fn next(&mut self) -> Option<T> {
        self.rx.try_recv().ok()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<'a, T> IntoIterator for &'a Receiver<T> {
    type Item = T;
    type IntoIter = Iter<'a, T>;

    fn into_iter(self) -> Iter<'a, T> {
        self.iter()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<T> Iterator for IntoIter<T> {
    type Item = T;
    fn next(&mut self) -> Option<T> {
        self.rx.recv().ok()
    }
}

#[stable(feature = "receiver_into_iter", since = "1.1.0")]
impl<T> IntoIterator for Receiver<T> {
    type Item = T;
    type IntoIter = IntoIter<T>;

    fn into_iter(self) -> IntoIter<T> {
        IntoIter { rx: self }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Drop for Receiver<T> {
    fn drop(&mut self) {
        match *unsafe { self.inner() } {
            Flavor::Oneshot(ref p) => p.drop_port(),
            Flavor::Stream(ref p) => p.drop_port(),
            Flavor::Shared(ref p) => p.drop_port(),
            Flavor::Sync(ref p) => p.drop_port(),
        }
    }
}

#[stable(feature = "mpsc_debug", since = "1.8.0")]
impl<T> fmt::Debug for Receiver<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Receiver").finish_non_exhaustive()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Debug for SendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SendError").finish_non_exhaustive()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Display for SendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        "sending on a closed channel".fmt(f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Send> error::Error for SendError<T> {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "sending on a closed channel"
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Debug for TrySendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TrySendError::Full(..) => "Full(..)".fmt(f),
            TrySendError::Disconnected(..) => "Disconnected(..)".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> fmt::Display for TrySendError<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TrySendError::Full(..) => "sending on a full channel".fmt(f),
            TrySendError::Disconnected(..) => "sending on a closed channel".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Send> error::Error for TrySendError<T> {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            TrySendError::Full(..) => "sending on a full channel",
            TrySendError::Disconnected(..) => "sending on a closed channel",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl<T> From<SendError<T>> for TrySendError<T> {
    /// 将 `SendError<T>` 转换为 `TrySendError<T>`。
    ///
    /// 这种转换总是返回一个包含 `SendError<T>` 中数据的 `TrySendError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: SendError<T>) -> TrySendError<T> {
        match err {
            SendError(t) => TrySendError::Disconnected(t),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for RecvError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        "receiving on a closed channel".fmt(f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl error::Error for RecvError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "receiving on a closed channel"
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for TryRecvError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            TryRecvError::Empty => "receiving on an empty channel".fmt(f),
            TryRecvError::Disconnected => "receiving on a closed channel".fmt(f),
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl error::Error for TryRecvError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            TryRecvError::Empty => "receiving on an empty channel",
            TryRecvError::Disconnected => "receiving on a closed channel",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl From<RecvError> for TryRecvError {
    /// 将 `RecvError` 转换为 `TryRecvError`。
    ///
    /// 此转换始终返回 `TryRecvError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: RecvError) -> TryRecvError {
        match err {
            RecvError => TryRecvError::Disconnected,
        }
    }
}

#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")]
impl fmt::Display for RecvTimeoutError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            RecvTimeoutError::Timeout => "timed out waiting on channel".fmt(f),
            RecvTimeoutError::Disconnected => "channel is empty and sending half is closed".fmt(f),
        }
    }
}

#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")]
impl error::Error for RecvTimeoutError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match *self {
            RecvTimeoutError::Timeout => "timed out waiting on channel",
            RecvTimeoutError::Disconnected => "channel is empty and sending half is closed",
        }
    }
}

#[stable(feature = "mpsc_error_conversions", since = "1.24.0")]
impl From<RecvError> for RecvTimeoutError {
    /// 将 `RecvError` 转换为 `RecvTimeoutError`。
    ///
    /// 此转换始终返回 `RecvTimeoutError::Disconnected`。
    ///
    /// 没有在堆上分配数据。
    fn from(err: RecvError) -> RecvTimeoutError {
        match err {
            RecvError => RecvTimeoutError::Disconnected,
        }
    }
}