Receiver in std::sync::mpmc - Rust
Description: The receiving half of Rust’s `channel` (or `sync_channel`) type. Different threads can share this `Receiver` by cloning it.

## Receiver

# Struct Receiver

Source

    pub struct Receiver<T> { /* private fields */ }

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)
Expand description

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

## Implementations§

Source§

### impl<T> Receiver<T>

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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.

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source§

### impl<T> Receiver<T>

Source

#### pub fn is_empty(&self) -> bool

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

#### pub fn is_full(&self) -> bool

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

#### pub fn len(&self) -> usize

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

Source

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

🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)

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

## Trait Implementations§

Source§

### impl<T> Clone for Receiver<T>

Source§

#### fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 · Source§

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
Source§

### impl<T> Debug for Receiver<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

### impl<T> Drop for Receiver<T>

Source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

### impl<'a, T> IntoIterator for &'a Receiver<T>

Source§

#### type Item = T

The type of the elements being iterated over.
Source§

#### type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?
Source§

#### fn into_iter(self) -> Iter<'a, T> ⓘ

Creates an iterator from a value. Read more
Source§

### impl<T> IntoIterator for Receiver<T>

Source§

#### type Item = T

The type of the elements being iterated over.
Source§

#### type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?
Source§

#### fn into_iter(self) -> IntoIter<T> ⓘ

Creates an iterator from a value. Read more
Source§

### impl<T> RefUnwindSafe for Receiver<T>

Source§

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

Source§

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

Source§

### impl<T> UnwindSafe for Receiver<T>

## Auto Trait Implementations§

§

### impl<T> Freeze for Receiver<T>

§

### impl<T> Unpin for Receiver<T>

## Blanket Implementations§

Source§

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

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

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

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Mutably borrows from an owned value. Read more
Source§

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

Source§

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

🔬This is a nightly-only experimental API. (`clone_to_uninit` #126799)
Performs copy-assignment from `self` to `dest`. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

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

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

Source§

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

Source§

#### type Owned = T

The resulting type after obtaining ownership.
Source§

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

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

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

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

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.