Expand description
Multi-producer, multi-consumer FIFO queue communication primitive.
This crate provides a multi-producer, multi-consumer, message-based communication channel, concretely defined among two types:
Sender
Receiver
A Sender
is used to send data to a Receiver
. Both senders and receivers
are clone-able such that sending and receiving can be done concurrently
across threads.
§Disconnection
The send and receive operations will all return a Result
indicating
whether the operation succeeded or not. An unsuccessful operation is
normally indicative of the other half of the channel having “hung up” by
being dropped in its corresponding thread.
Once half of a channel has been deallocated, most operations can no longer
continue to make progress, so Err
will be returned.
§Examples
Simple usage:
use std::thread;
let (tx, rx) = two_lock_queue::channel(1024);
for i in 0..10 {
let tx = tx.clone();
thread::spawn(move || {
tx.send(i).unwrap();
});
}
let mut threads = vec![];
for _ in 0..10 {
let rx = rx.clone();
threads.push(thread::spawn(move || {
let j = rx.recv().unwrap();
assert!(0 <= j && j < 10);
}));
}
for th in threads {
th.join().unwrap();
}
§Algorithm
The algorithm is a variant of the Michael-Scott two lock queue found as part
of Java’s LinkedBlockingQueue. The queue uses a mutex to guard the head
pointer and a mutex to guard the tail pointer. Most of the time, send and
receive operations will only need to lock a single mutex. An AtomicUsize
is used to track the number of elements in the queue as well as handle
coordination between the producer and consumer halves.
Structs§
- Receiver
- The receiving-half of the channel.
- Recv
Error - An error returned from the
recv
function on aReceiver
. - Send
Error - An error returned from the
Sender::send
orSyncSender::send
function on channels. - Sender
- The sending-half of the channel.
Enums§
- Recv
Timeout Error - This enumeration is the list of possible errors that made
recv_timeout
unable to return data when called. This can occur with both achannel
and async_channel
. - Send
Timeout Error - Possible errors that
send_timeout
could encounter. - TryRecv
Error - This enumeration is the list of the possible reasons that
try_recv
could not return data when called. This can occur with both achannel
and async_channel
. - TrySend
Error - This enumeration is the list of the possible error outcomes for the
try_send
method.