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 secondsRun

## Methods

### `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

####
ⓘImportant traits for Iter<'a, T>

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

`impl<'a, T> Iterator for Iter<'a, T> type Item = T;`
`pub fn iter(&self) -> Iter<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

####
ⓘImportant traits for TryIter<'a, T>

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

`impl<'a, T> Iterator for TryIter<'a, T> type Item = T;`
`pub fn try_iter(&self) -> TryIter<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<T> !Sync for Receiver<T>`[src]

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

### `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?

####
ⓘImportant traits for Iter<'a, T>

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

`impl<'a, T> Iterator for Iter<'a, T> type Item = T;`
`fn into_iter(self) -> Iter<'a, 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?

####
ⓘImportant traits for IntoIter<T>

### Important traits for IntoIter<T>

`impl<T> Iterator for IntoIter<T> type Item = T;`
`fn into_iter(self) -> IntoIter<T>`[src]

Creates an iterator from a value. Read more

## Blanket Implementations

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

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[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?

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

Creates an iterator from a value. Read more

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

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

Performs the conversion.

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

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

The type returned in the event of a conversion error.

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

Performs the conversion.

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

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

Performs the conversion.

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

####
ⓘImportant traits for &'_ mut I

### Important 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`
`fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

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

####
ⓘImportant traits for &'_ mut I

### Important 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`
`fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

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

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

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)