Module std::sync::mpsc1.0.0[][src]

Expand description

多生产者,单消费者 FIFO 队列通信原语。

该模块通过通道提供基于消息的通信,具体定义为以下三种类型:

SenderSyncSender 用于将数据发送到 Receiver。 两个发送者都是可克隆的 (multi-producer),因此许多线程可以同时发送到一个接收者 (single-consumer)。

这些通道有两种口味:

  1. 异步,无限缓冲的通道。 channel 函数将返回 (Sender, Receiver) 元组,其中所有发送都是异步的 (它们从不阻塞)。 通道在概念上具有无限的缓冲区。

  2. 同步的有界通道。 sync_channel 函数将返回 (SyncSender, Receiver) 元组,其中待处理消息的存储是固定大小的预分配缓冲区。 所有的发送都将被阻塞,直到有可用的缓冲区空间。 请注意,允许的界限为 0,从而使通道成为 “rendezvous” 通道,每个发送者在该通道上原子地将消息传递给接收者。

Disconnection

通道上的发送和接收操作都将返回 Result,指示该操作是否成功。 不成功的操作通常通过将其丢弃在相应线程中来指示具有 “hung up” 的通道的另一半。

释放通道的一半后,大多数操作将不再继续进行,因此将返回 Err。 许多应用程序将继续对该模块返回的结果进行 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);
Run

共享用法:

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);
}
Run

传播 panics:

use std::sync::mpsc::channel;

// 调用 recv() 将返回错误,因为通道已挂起 (或已释放)
//
let (tx, rx) = channel::<i32>();
drop(tx);
assert!(rx.recv().is_err());
Run

同步通道:

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();
Run

无限接收循环:

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");
Run

Structs

IntoIter

Receiver 上由消息接收者拥有的迭代器,该迭代器由 接收者::into_iter 创建。

Iter

iterReceiver 上创建的消息上的迭代器。

Receiver

Rust 的 channel (或 sync_channel) 类型的接收一半。 这一半只能由一个线程拥有。

RecvError

Receiver 上的 recv 函数返回错误。

SendError

X X 上的 Sender::sendSyncSender::send 函数返回错误。

Sender

Rust 的异步 channel 类型的发送一半。 这一半只能由一个线程拥有,但可以克隆以发送给其他线程。

SyncSender

Rust 的同步 sync_channel 类型的发送一半。

TryIter

尝试产生 try_iter 创建的 Receiver 的所有挂起值的迭代器。

Enums

RecvTimeoutError

该枚举是导致 recv_timeout 在调用时无法返回数据的可能错误的列表。 channelsync_channel 都可能发生这种情况。

TryRecvError

该枚举是 try_recv 在调用时无法返回数据的可能原因的列表。 channelsync_channel 都可能发生这种情况。

TrySendError

此枚举是 try_send 方法可能出现的错误结果的列表。

Functions

channel

创建一个新的异步通道,返回 sender/receiver 一半。 在 Sender 上发送的所有数据将以与发送时相同的顺序在 Receiver 上可用,并且没有 send 将阻塞调用线程 (此通道具有一个 “infinite buffer”,与 sync_channel 不同,它将在达到其缓冲区限制后阻塞)。 recv 当至少有一个 Sender 活着 (包括克隆) 时,将阻塞直到消息可用。

sync_channel

创建一个新的同步有界通道。 SyncSender 上发送的所有数据将以与发送相同的顺序在 Receiver 上可用。 像异步 channel 一样,Receiver 将阻塞直到消息可用为止。 sync_channel 但是,发送者的语义差异很大。