std::sync::mpsc::Receiver - Rust
Description: API documentation for the Rust `Receiver` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, Receiver

# 1.0.0[−][src]Struct std::sync::mpsc::Receiver

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

The receiving half of Rust's `channel` (or `sync_channel`) type. This half can only be owned by one thread.

Messages sent to the channel can be retrieved using `recv`.

# Examples

    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)); // block for two seconds
        send.send("Delayed for 2 seconds").unwrap();
    });

    println!("{}", recv.recv().unwrap()); // Received immediately
    println!("Waiting...");
    println!("{}", recv.recv().unwrap()); // Received after 2 seconds

Run

## Implementations

### `impl<T> Receiver<T>`[src]

#### `pub fn try_recv(&self) -> Result<T, TryRecvError>`[src]

Attempts to return a pending value on this receiver 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.

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

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

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

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

Run

#### `pub fn recv(&self) -> Result<T, RecvError>`[src]

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. Once a message is sent to the corresponding `Sender` (or `SyncSender`), 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

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

Run

Buffering behavior:

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

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

Run

#### `pub fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError>`1.12.0[src]

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. Once a message is sent to the corresponding `Sender` (or `SyncSender`), 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.

# Known Issues

There is currently a known issue (see `#39364`) that causes `recv_timeout` to panic unexpectedly with the following example:

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

    let (tx, rx) = channel::<String>();

    thread::spawn(move || {
        let d = Duration::from_millis(10);
        loop {
            println!("recv");
            let _r = rx.recv_timeout(d);
        }
    });

    thread::sleep(Duration::from_millis(100));
    let _c1 = tx.clone();

    thread::sleep(Duration::from_secs(1));

Run

# Examples

Successfully receiving value before encountering timeout:

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

Run

Receiving an error upon reaching timeout:

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

Run

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

🔬 This is a nightly-only experimental API. (`deadline_api` #46316)

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` (or `SyncSender`), 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(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')
    );

Run

Receiving an error upon reaching deadline:

    #![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)
    );

Run

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

### Notable traits for Iter<'a, T>

`impl<'a, T> Iterator for Iter<'a, T> type Item = T;`
`[src]

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

# Examples

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

Run

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

### Notable traits for TryIter<'a, T>

`impl<'a, T> Iterator for TryIter<'a, T> type Item = T;`
`1.15.0[src]

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

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

Run

## Trait Implementations

### `impl<T> Debug for Receiver<T>`1.8.0[src]

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

Formats the value using the given formatter. Read more

### `impl<T> Drop for Receiver<T>`[src]

#### `fn drop(&mut self)`[src]

Executes the destructor for this type. Read more

### `impl<'a, T> IntoIterator for &'a Receiver<T>`1.1.0[src]

#### `type Item = T`

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

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

### Notable traits for Iter<'a, T>

`impl<'a, T> Iterator for Iter<'a, T> type Item = T;`
`[src]

Creates an iterator from a value. Read more

### `impl<T> IntoIterator for Receiver<T>`1.1.0[src]

#### `type Item = T`

The type of the elements being iterated over.

#### `type IntoIter = IntoIter<T>`

Which kind of iterator are we turning this into?

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

### Notable traits for IntoIter<T>

`impl<T> Iterator for IntoIter<T> type Item = T;`
`[src]

Creates an iterator from a value. Read more

### `impl<T: Send> Send for Receiver<T>`[src]

### `impl<T> !Sync for Receiver<T>`[src]

## Auto Trait Implementations

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

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

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

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId`[src]

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

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T`[src]

#### `pub fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U`[src]

Performs the conversion.

### `impl<I> IntoIterator for I where
I: Iterator,` [src]

#### `type Item = <I as Iterator>::Item`

The type of the elements being iterated over.

#### `type IntoIter = I`

Which kind of iterator are we turning this into?

#### `pub fn into_iter(self) -> I`[src]

Creates an iterator from a value. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

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

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.