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

# Struct tokio::sync::mpsc::Receiver [−] [src]

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

Receive values from the associated `Sender`.

Instances are created by the `channel` function.

This receiver can be turned into a `Stream` using `ReceiverStream`.

## Implementations

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

#### `pub async fn recv(&mut self) -> Option<T>` [src]

Receives the next value for this receiver.

This method returns `None` if the channel has been closed and there are no remaining messages in the channel's buffer. This indicates that no further values can ever be received from this `Receiver`. The channel is closed when all senders have been dropped, or when `close` is called.

If there are no messages in the channel's buffer, but the channel has not yet been closed, this method will sleep until a message is sent or the channel is closed.

Note that if `close` is called, but there are still outstanding `Permits` from before it was closed, the channel is not considered closed by `recv` until the permits are released.

# Examples

    use tokio::sync::mpsc;

    #[tokio::main]
    async fn main() {
        let (tx, mut rx) = mpsc::channel(100);

        tokio::spawn(async move {
            tx.send("hello").await.unwrap();
        });

        assert_eq!(Some("hello"), rx.recv().await);
        assert_eq!(None, rx.recv().await);
    }

Values are buffered:

    use tokio::sync::mpsc;

    #[tokio::main]
    async fn main() {
        let (tx, mut rx) = mpsc::channel(100);

        tx.send("hello").await.unwrap();
        tx.send("world").await.unwrap();

        assert_eq!(Some("hello"), rx.recv().await);
        assert_eq!(Some("world"), rx.recv().await);
    }

#### `pub fn blocking_recv(&mut self) -> Option<T>` [src]

Blocking receive to call outside of asynchronous contexts.

This method returns `None` if the channel has been closed and there are no remaining messages in the channel's buffer. This indicates that no further values can ever be received from this `Receiver`. The channel is closed when all senders have been dropped, or when `close` is called.

If there are no messages in the channel's buffer, but the channel has not yet been closed, this method will block until a message is sent or the channel is closed.

This method is intended for use cases where you are sending from asynchronous code to synchronous code, and will work even if the sender is not using `blocking_send` to send the message.

Note that if `close` is called, but there are still outstanding `Permits` from before it was closed, the channel is not considered closed by `blocking_recv` until the permits are released.

# Panics

This function panics if called within an asynchronous execution context.

# Examples

    use std::thread;
    use tokio::runtime::Runtime;
    use tokio::sync::mpsc;

    fn main() {
        let (tx, mut rx) = mpsc::channel::<u8>(10);

        let sync_code = thread::spawn(move || {
            assert_eq!(Some(10), rx.blocking_recv());
        });

        Runtime::new()
            .unwrap()
            .block_on(async move {
                let _ = tx.send(10).await;
            });
        sync_code.join().unwrap()
    }

#### `pub fn close(&mut self)` [src]

Closes the receiving half of a channel without dropping it.

This prevents any further messages from being sent on the channel while still enabling the receiver to drain messages that are buffered. Any outstanding `Permit` values will still be able to send messages.

To guarantee that no messages are dropped, after calling `close()`, `recv()` must be called until `None` is returned. If there are outstanding `Permit` values, the `recv` method will not return `None` until those are released.

# Examples

    use tokio::sync::mpsc;

    #[tokio::main]
    async fn main() {
        let (tx, mut rx) = mpsc::channel(20);

        tokio::spawn(async move {
            let mut i = 0;
            while let Ok(permit) = tx.reserve().await {
                permit.send(i);
                i += 1;
            }
        });

        rx.close();

        while let Some(msg) = rx.recv().await {
            println!("got {}", msg);
        }

        // Channel closed and no messages are lost.
    }

#### `pub fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>>` [src]

Polls to receive the next message on this channel.

This method returns:

- `Poll::Pending` if no messages are available but the channel is not closed.
- `Poll::Ready(Some(message))` if a message is available.
- `Poll::Ready(None)` if the channel has been closed and all messages sent before it was closed have been received.

When the method returns `Poll::Pending`, the `Waker` in the provided `Context` is scheduled to receive a wakeup when a message is sent on any receiver, or when the channel is closed. Note that on multiple calls to `poll_recv`, only the `Waker` from the `Context` passed to the most recent call is scheduled to receive a wakeup.

## Trait Implementations

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

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

Formats the value using the given formatter. Read more

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

## Auto Trait Implementations

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

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

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

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

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

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [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 F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [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<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.