Struct Receiver

pub struct Receiver<T> { pub(in ::sync::mpmc) flavor: ReceiverFlavor<T> }

The receiving half of Rust's channel (or sync_channel) type. Different threads can share this Receiver by cloning it.

Messages sent to the channel can be retrieved using recv.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc::channel;
use std::thread;
use std::time::Duration;

let (send, recv) = channel();

let tx_thread = thread::spawn(move || {
    send.send("Hello world!").unwrap();
    thread::sleep(Duration::from_secs(2)); // block for two seconds
    send.send("Delayed for 2 seconds").unwrap();
});

let (rx1, rx2) = (recv.clone(), recv.clone());
let rx_thread_1 = thread::spawn(move || {
    println!("{}", rx1.recv().unwrap()); // Received immediately
});
let rx_thread_2 = thread::spawn(move || {
    println!("{}", rx2.recv().unwrap()); // Received after 2 seconds
});

tx_thread.join().unwrap();
rx_thread_1.join().unwrap();
rx_thread_2.join().unwrap();

Fields

flavor: ReceiverFlavor<T>

Implementations

impl<T> Receiver<T>

fn try_recv(&self) -> Result<T, TryRecvError>

Attempts to receive a message from the channel without blocking.

This method will never block the caller in order to wait for data to become available. Instead, this will always return immediately with a possible option of pending data on the channel. (See std::sync for precise guarantees on blocking.)

If called on a zero-capacity channel, this method will receive a message only if there happens to be a send operation on the other side of the channel at the same time.

This is useful for a flavor of "optimistic check" before deciding to block on a receiver.

Compared with recv, this function has two failure cases instead of one (one for disconnection, one for an empty buffer).

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc::{Receiver, channel};

let (_, receiver): (_, Receiver<i32>) = channel();

assert!(receiver.try_recv().is_err());

fn recv(&self) -> Result<T, RecvError>

Attempts to wait for a value on this receiver, returning an error if the corresponding channel has hung up.

This function will always block the current thread if there is no data available and it's possible for more data to be sent (at least one sender still exists). Once a message is sent to the corresponding Sender, this receiver will wake up and return that message.

If the corresponding Sender has disconnected, or it disconnects while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;

let (send, recv) = mpmc::channel();
let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
});

handle.join().unwrap();

assert_eq!(Ok(1), recv.recv());

Buffering behavior:

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;
use std::sync::mpmc::RecvError;

let (send, recv) = mpmc::channel();
let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
    send.send(2).unwrap();
    send.send(3).unwrap();
    drop(send);
});

// wait for the thread to join so we ensure the sender is dropped
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());

fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError>

Attempts to wait for a value on this receiver, returning an error if the corresponding channel has hung up, or if it waits more than timeout.

This function will always block the current thread if there is no data available and it's possible for more data to be sent (at least one sender still exists). Once a message is sent to the corresponding Sender, this receiver will wake up and return that message.

If the corresponding Sender has disconnected, or it disconnects while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.

Examples

Successfully receiving value before encountering timeout:

#![feature(mpmc_channel)]

use std::thread;
use std::time::Duration;
use std::sync::mpmc;

let (send, recv) = mpmc::channel();

thread::spawn(move || {
    send.send('a').unwrap();
});

assert_eq!(
    recv.recv_timeout(Duration::from_millis(400)),
    Ok('a')
);

Receiving an error upon reaching timeout:

#![feature(mpmc_channel)]

use std::thread;
use std::time::Duration;
use std::sync::mpmc;

let (send, recv) = mpmc::channel();

thread::spawn(move || {
    thread::sleep(Duration::from_millis(800));
    send.send('a').unwrap();
});

assert_eq!(
    recv.recv_timeout(Duration::from_millis(400)),
    Err(mpmc::RecvTimeoutError::Timeout)
);

fn recv_deadline(&self, deadline: Instant) -> Result<T, RecvTimeoutError>

Attempts to wait for a value on this receiver, returning an error if the corresponding channel has hung up, or if deadline is reached.

This function will always block the current thread if there is no data available and it's possible for more data to be sent. Once a message is sent to the corresponding Sender, then this receiver will wake up and return that message.

If the corresponding Sender has disconnected, or it disconnects while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.

Examples

Successfully receiving value before reaching deadline:

#![feature(mpmc_channel)]

use std::thread;
use std::time::{Duration, Instant};
use std::sync::mpmc;

let (send, recv) = mpmc::channel();

thread::spawn(move || {
    send.send('a').unwrap();
});

assert_eq!(
    recv.recv_deadline(Instant::now() + Duration::from_millis(400)),
    Ok('a')
);

Receiving an error upon reaching deadline:

#![feature(mpmc_channel)]

use std::thread;
use std::time::{Duration, Instant};
use std::sync::mpmc;

let (send, recv) = mpmc::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(mpmc::RecvTimeoutError::Timeout)
);

fn try_iter(&self) -> TryIter<'_, T>

Returns an iterator that will attempt to yield all pending values. It will return None if there are no more pending values or if the channel has hung up. The iterator will never [panic!] or block the user by waiting for values.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc::channel;
use std::thread;
use std::time::Duration;

let (sender, receiver) = channel();

// nothing is in the buffer yet
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();
});

// nothing is in the buffer yet
assert!(receiver.try_iter().next().is_none());

// block for two seconds
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);

impl<T> Receiver<T>

fn is_empty(&self) -> bool

Returns true if the channel is empty.

Note: Zero-capacity channels are always empty.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;

let (send, recv) = mpmc::channel();

assert!(recv.is_empty());

let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
});

handle.join().unwrap();

assert!(!recv.is_empty());

fn is_full(&self) -> bool

Returns true if the channel is full.

Note: Zero-capacity channels are always full.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;

let (send, recv) = mpmc::sync_channel(1);

assert!(!recv.is_full());

let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
});

handle.join().unwrap();

assert!(recv.is_full());

fn len(&self) -> usize

Returns the number of messages in the channel.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;

let (send, recv) = mpmc::channel();

assert_eq!(recv.len(), 0);

let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
});

handle.join().unwrap();

assert_eq!(recv.len(), 1);

fn capacity(&self) -> Option<usize>

If the channel is bounded, returns its capacity.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;
use std::thread;

let (send, recv) = mpmc::sync_channel(3);

assert_eq!(recv.capacity(), Some(3));

let handle = thread::spawn(move || {
    send.send(1u8).unwrap();
});

handle.join().unwrap();

assert_eq!(recv.capacity(), Some(3));

fn same_channel(&self, other: &Receiver<T>) -> bool

Returns true if receivers belong to the same channel.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc;

let (_, rx1) = mpmc::channel::<i32>();
let (_, rx2) = mpmc::channel::<i32>();

assert!(rx1.same_channel(&rx1));
assert!(!rx1.same_channel(&rx2));

fn iter(&self) -> Iter<'_, T>

Returns an iterator that will block waiting for messages, but never [panic!]. It will return None when the channel has hung up.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc::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);

fn is_disconnected(&self) -> bool

Returns true if the channel is disconnected.

Note that a return value of false does not guarantee the channel will remain connected. The channel may be disconnected immediately after this method returns, so a subsequent Receiver::recv may still fail with RecvError.

Examples

#![feature(mpmc_channel)]

use std::sync::mpmc::channel;

let (tx, rx) = channel::<i32>();
assert!(!rx.is_disconnected());
drop(tx);
assert!(rx.is_disconnected());

Trait Implementations

impl<T> Clone for Receiver<T>

fn clone(&self) -> Self

impl<T> Debug for Receiver<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<T> Drop for Receiver<T>

fn drop(&mut self)

impl<T> IntoIterator for Receiver<T>

type Item = T;
type IntoIter = IntoIter<T>;
fn into_iter(self) -> IntoIter<T>

impl<T> RefUnwindSafe for Receiver<T>

impl<T> UnwindSafe for Receiver<T>

impl<T: Send> Send for Receiver<T>

impl<T: Send> Sync for Receiver<T>

Auto Trait Implementations

impl<T> Freeze for Receiver<T> where ReceiverFlavor<T>: Freeze,

impl<T> Unpin for Receiver<T> where ReceiverFlavor<T>: Unpin,

impl<T> UnsafeUnpin for Receiver<T> where ReceiverFlavor<T>: UnsafeUnpin,

Blanket Implementations

impl<T> Any for Receiver<T> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Receiver<T> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Receiver<T> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for Receiver<T> where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for Receiver<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> SizeHint for Receiver<T> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for Receiver<T>

impl<T> ToOwned for Receiver<T> where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T, U> Into<U> for Receiver<T> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Receiver<T> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for Receiver<T> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>