//! 多生产者，单消费者 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;

// MPSC 通道是作为 MPMC 通道的包装器构建的，它是从 `crossbeam-channel` crate 移植而来的。
// MPMC 通道没有公开，但如果您对实现感到好奇，那就是一切。
//
//

use crate::error;
use crate::fmt;
use crate::sync::mpmc;
use crate::time::{Duration, Instant};

/// 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: mpmc::Receiver<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`]。
///
///
/// [`into_iter`]: Receiver::into_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.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: mpmc::Sender<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 {msg} received");
///
/// // 现在将打印 "Thread unblocked!"
///
/// msg = receiver.recv().unwrap();
/// println!("message {msg} received");
///
/// msg = receiver.recv().unwrap();
///
/// println!("message {msg} received");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SyncSender<T> {
    inner: mpmc::Sender<T>,
}

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

/// 从 **通道** 上的 [`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),
}

/// 创建一个新的异步通道，返回 sender/receiver 一半。
/// 在 [`Sender`] 上发送的所有数据将以与发送时相同的顺序在 [`Receiver`] 上可用，并且没有 [`send`] 将阻塞调用线程 (此通道具有一个 "无限缓冲区"，与 [`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());
/// ```
///
///
///
///
///
///
///
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
    let (tx, rx) = mpmc::channel();
    (Sender { inner: tx }, Receiver { inner: rx })
}

/// 创建一个新的同步有界通道。
/// [`SyncSender`] 上发送的所有数据将以与发送相同的顺序在 [`Receiver`] 上可用。
/// 像异步 [`channel`] 一样，[`Receiver`] 将阻塞直到消息可用为止。
/// 然而，`sync_channel` 在发送者的语义上有很大不同。
///
/// 该通道具有内部缓冲区，消息将在该缓冲区上排队。
/// `bound` 指定缓冲区大小。
/// 当内部缓冲区已满时，future 将发送 *block*，等待缓冲区打开。
/// 请注意，缓冲区大小为 0 是有效的，在这种情况下，它变为 "会合通道"，其中每个 [`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);
/// ```
///
///
///
///
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn sync_channel<T>(bound: usize) -> (SyncSender<T>, Receiver<T>) {
    let (tx, rx) = mpmc::sync_channel(bound);
    (SyncSender { inner: tx }, Receiver { inner: rx })
}

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

impl<T> Sender<T> {
    /// 尝试在此通道上发送值，如果无法发送，则将其返回。
    ///
    /// 当确定通道的另一端尚未挂断时，发送成功。
    /// 不成功的发送将是相应的接收者已被重新分配的发送。
    /// 请注意，返回值 [`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>> {
        self.inner.send(t)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Clone for Sender<T> {
    /// 克隆发送者以发送到其他线程。
    ///
    /// 请注意，请注意发送方的生命周期，因为所有发送方 (包括原始发送方) 都需要丢弃，以便 [`Receiver::recv`] 停止阻塞。
    ///
    ///
    fn clone(&self) -> Sender<T> {
        Sender { inner: self.inner.clone() }
    }
}

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

#[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> {
    /// 在此同步通道上发送一个值。
    ///
    /// 该函数将阻塞，直到内部缓冲区中的空间可用或接收者可以将消息传递给它为止。
    ///
    /// 请注意，如果此通道上有缓冲区，则成功发送并不能保证接收者会看到数据。
    /// 该项可能会排队在内部缓冲区中，以供接收者在以后的时间接收。
    /// 但是，如果缓冲区大小为 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)
    }

    /// 尝试在此通道上发送值而不会阻塞。
    ///
    /// 此方法不同于 [`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 {msg} received");
    ///
    /// msg = receiver.recv().unwrap();
    /// println!("message {msg} received");
    ///
    /// // 第三条消息可能从未发送过
    /// match receiver.try_recv() {
    ///     Ok(msg) => println!("message {msg} received"),
    ///     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)
    }

    // 尝试在此接收者上发送一个值，如果相应的通道已挂断或等待时间超过 `timeout`，则返回错误。
    //
    //
    // 此方法目前是私有的，仅用于测试。
    #[allow(unused)]
    fn send_timeout(&self, t: T, timeout: Duration) -> Result<(), mpmc::SendTimeoutError<T>> {
        self.inner.send_timeout(t, timeout)
    }
}

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

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

#[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> {
    /// 尝试在不阻塞的情况下在此接收者上返回挂起的值。
    ///
    /// 此方法决不会阻塞调用者，以等待数据可用。
    /// 取而代之的是，它总是立即返回，并可能在通道上保留未决数据。
    ///
    /// 在决定阻塞接收者之前，这对于 "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> {
        self.inner.try_recv()
    }

    /// 尝试等待此接收者上的值，如果相应的通道已挂起，则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在)，此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`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> {
        self.inner.recv()
    }

    /// 尝试等待此接收器上的值，如果相应的通道已挂起，或者等待的时间超过 `timeout`，则返回错误。
    ///
    /// 如果没有可用数据并且有可能发送更多数据 (至少一个发送者仍然存在)，此函数将始终阻塞当前线程。
    /// 一旦消息发送到相应的 [`Sender`] (或 [`SyncSender`])，该接收者将唤醒并返回该消息。
    ///
    /// 如果相应的 [`Sender`] 断开连接，或者在此调用阻塞时断开连接，则此调用将唤醒并返回 [`Err`]，以指示该通道上再也不会收到任何消息。
    ///
    /// 但是，由于缓冲了通道，因此在断开连接之前发送的消息仍将被正确接收。
    ///
    /// # 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> {
        self.inner.recv_timeout(timeout)
    }

    /// 尝试等待此接收器上的值，如果相应的通道已挂起，或者到达 `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> {
        self.inner.recv_deadline(deadline)
    }

    /// 返回一个迭代器，该迭代器将阻止等待消息，但不会阻止 [`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) {}
}

#[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> 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> 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,
        }
    }
}