W3cubDocs

/Rust

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

Methods

impl<T> Receiver<T> [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());

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

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

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

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

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

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

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

ⓘImportant traits for Iter<'a, T>
impl<'a, T> Iterator for Iter<'a, T>
    type Item = T;

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

ⓘImportant traits for TryIter<'a, T>
impl<'a, T> Iterator for TryIter<'a, T>
    type Item = 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

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

Trait Implementations

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

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

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

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

ⓘImportant traits for Iter<'a, T>
impl<'a, T> Iterator for Iter<'a, T>
    type Item = T;

Creates an iterator from a value. Read more

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

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

ⓘImportant traits for IntoIter<T>
impl<T> Iterator for IntoIter<T>
    type Item = T;

Creates an iterator from a value. Read more

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

Executes the destructor for this type. Read more

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

Formats the value using the given formatter. Read more

Blanket Implementations

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from #33417)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from #33417)

Performs the conversion.

impl<T> From for T [src]

Performs the conversion.

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

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

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

🔬 This is a nightly-only experimental API. (try_from #33417)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from #33417)

Performs the conversion.

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

Performs the conversion.

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

ⓘImportant traits for &'a mut I
impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized, 
    type Item = <I as Iterator>::Item;
impl<'a, R: Read + ?Sized> Read for &'a mut R
impl<'a, W: Write + ?Sized> Write for &'a mut W

Immutably borrows from an owned value. Read more

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

ⓘImportant traits for &'a mut I
impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized, 
    type Item = <I as Iterator>::Item;
impl<'a, R: Read + ?Sized> Read for &'a mut R
impl<'a, W: Write + ?Sized> Write for &'a mut W

Mutably borrows from an owned value. Read more

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

🔬 This is a nightly-only experimental API. (get_type_id #27745)this method will likely be replaced by an associated static

Gets the TypeId of self. Read more

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/sync/mpsc/struct.Receiver.html