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

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

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

Receiving-half of the `broadcast` channel.

Must not be used concurrently. Messages may be retrieved using `recv`.

To turn this receiver into a `Stream`, you can use the `BroadcastStream` wrapper.

# Examples

    use tokio::sync::broadcast;

    #[tokio::main]
    async fn main() {
        let (tx, mut rx1) = broadcast::channel(16);
        let mut rx2 = tx.subscribe();

        tokio::spawn(async move {
            assert_eq!(rx1.recv().await.unwrap(), 10);
            assert_eq!(rx1.recv().await.unwrap(), 20);
        });

        tokio::spawn(async move {
            assert_eq!(rx2.recv().await.unwrap(), 10);
            assert_eq!(rx2.recv().await.unwrap(), 20);
        });

        tx.send(10).unwrap();
        tx.send(20).unwrap();
    }

## Implementations

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

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

Receives the next value for this receiver.

Each `Receiver` handle will receive a clone of all values sent after it has subscribed.

`Err(RecvError::Closed)` is returned when all `Sender` halves have dropped, indicating that no further values can be sent on the channel.

If the `Receiver` handle falls behind, once the channel is full, newly sent values will overwrite old values. At this point, a call to `recv` will return with `Err(RecvError::Lagged)` and the `Receiver`'s internal cursor is updated to point to the oldest value still held by the channel. A subsequent call to `recv` will return this value unless it has been since overwritten.

# Examples

    use tokio::sync::broadcast;

    #[tokio::main]
    async fn main() {
        let (tx, mut rx1) = broadcast::channel(16);
        let mut rx2 = tx.subscribe();

        tokio::spawn(async move {
            assert_eq!(rx1.recv().await.unwrap(), 10);
            assert_eq!(rx1.recv().await.unwrap(), 20);
        });

        tokio::spawn(async move {
            assert_eq!(rx2.recv().await.unwrap(), 10);
            assert_eq!(rx2.recv().await.unwrap(), 20);
        });

        tx.send(10).unwrap();
        tx.send(20).unwrap();
    }

Handling lag

    use tokio::sync::broadcast;

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

        tx.send(10).unwrap();
        tx.send(20).unwrap();
        tx.send(30).unwrap();

        // The receiver lagged behind
        assert!(rx.recv().await.is_err());

        // At this point, we can abort or continue with lost messages

        assert_eq!(20, rx.recv().await.unwrap());
        assert_eq!(30, rx.recv().await.unwrap());
    }

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

Attempts to return a pending value on this receiver without awaiting.

This is useful for a flavor of "optimistic check" before deciding to await on a receiver.

Compared with `recv`, this function has three failure cases instead of two (one for closed, one for an empty buffer, one for a lagging receiver).

`Err(TryRecvError::Closed)` is returned when all `Sender` halves have dropped, indicating that no further values can be sent on the channel.

If the `Receiver` handle falls behind, once the channel is full, newly sent values will overwrite old values. At this point, a call to `recv` will return with `Err(TryRecvError::Lagged)` and the `Receiver`'s internal cursor is updated to point to the oldest value still held by the channel. A subsequent call to `try_recv` will return this value unless it has been since overwritten. If there are no values to receive, `Err(TryRecvError::Empty)` is returned.

# Examples

    use tokio::sync::broadcast;

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

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

        tx.send(10).unwrap();

        let value = rx.try_recv().unwrap();
        assert_eq!(10, value);
    }

## 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> Drop for Receiver<T>` [src]

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

Executes the destructor for this type. Read more

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

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

## Auto Trait Implementations

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

### `impl<T> Unpin for Receiver<T>` [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.