pub struct Receiver<T> { /* private fields */ }
Expand description

The receiving side of a channel.

Receivers can be cloned and shared among threads. When all (active) receivers associated with a channel are dropped, the channel becomes closed. You can deactivate a receiver using Receiver::deactivate if you would like the channel to remain open without keeping active receivers around.

Implementations

Returns the channel capacity.

Examples
use async_broadcast::broadcast;

let (_s, r) = broadcast::<i32>(5);
assert_eq!(r.capacity(), 5);

Set the channel capacity.

There are times when you need to change the channel’s capacity after creating it. If the new_cap is less than the number of messages in the channel, the oldest messages will be dropped to shrink the channel.

Examples
use async_broadcast::{broadcast, TrySendError, TryRecvError};

let (s, mut r) = broadcast::<i32>(3);
assert_eq!(r.capacity(), 3);
s.try_broadcast(1).unwrap();
s.try_broadcast(2).unwrap();
s.try_broadcast(3).unwrap();

r.set_capacity(1);
assert_eq!(r.capacity(), 1);
assert_eq!(r.try_recv(), Err(TryRecvError::Overflowed(2)));
assert_eq!(r.try_recv().unwrap(), 3);
assert_eq!(r.try_recv(), Err(TryRecvError::Empty));
s.try_broadcast(1).unwrap();
assert_eq!(s.try_broadcast(2), Err(TrySendError::Full(2)));

r.set_capacity(2);
assert_eq!(r.capacity(), 2);
s.try_broadcast(2).unwrap();
assert_eq!(s.try_broadcast(2), Err(TrySendError::Full(2)));

If overflow mode is enabled on this channel.

Examples
use async_broadcast::broadcast;

let (_s, r) = broadcast::<i32>(5);
assert!(!r.overflow());

Set overflow mode on the channel.

When overflow mode is set, broadcasting to the channel will succeed even if the channel is full. It achieves that by removing the oldest message from the channel.

Examples
use async_broadcast::{broadcast, TrySendError, TryRecvError};

let (s, mut r) = broadcast::<i32>(2);
s.try_broadcast(1).unwrap();
s.try_broadcast(2).unwrap();
assert_eq!(s.try_broadcast(3), Err(TrySendError::Full(3)));
r.set_overflow(true);
assert_eq!(s.try_broadcast(3).unwrap(), Some(1));
assert_eq!(s.try_broadcast(4).unwrap(), Some(2));

assert_eq!(r.try_recv(), Err(TryRecvError::Overflowed(2)));
assert_eq!(r.try_recv().unwrap(), 3);
assert_eq!(r.try_recv().unwrap(), 4);
assert_eq!(r.try_recv(), Err(TryRecvError::Empty));

Closes the channel.

Returns true if this call has closed the channel and it was not closed already.

The remaining messages can still be received.

Examples
use async_broadcast::{broadcast, RecvError};

let (s, mut r) = broadcast(1);
s.broadcast(1).await.unwrap();
assert!(s.close());

assert_eq!(r.recv().await.unwrap(), 1);
assert_eq!(r.recv().await, Err(RecvError::Closed));

Returns true if the channel is closed.

Examples
use async_broadcast::{broadcast, RecvError};

let (s, r) = broadcast::<()>(1);
assert!(!s.is_closed());

drop(r);
assert!(s.is_closed());

Returns true if the channel is empty.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast(1);

assert!(s.is_empty());
s.broadcast(1).await;
assert!(!s.is_empty());

Returns true if the channel is full.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast(1);

assert!(!s.is_full());
s.broadcast(1).await;
assert!(s.is_full());

Returns the number of messages in the channel.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast(2);
assert_eq!(s.len(), 0);

s.broadcast(1).await;
s.broadcast(2).await;
assert_eq!(s.len(), 2);

Returns the number of receivers for the channel.

This does not include inactive receivers. Use Receiver::inactive_receiver_count if you are interested in that.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast::<()>(1);
assert_eq!(s.receiver_count(), 1);
let r = r.deactivate();
assert_eq!(s.receiver_count(), 0);

let r2 = r.activate_cloned();
assert_eq!(r.receiver_count(), 1);
assert_eq!(r.inactive_receiver_count(), 1);

Returns the number of inactive receivers for the channel.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast::<()>(1);
assert_eq!(s.receiver_count(), 1);
let r = r.deactivate();
assert_eq!(s.receiver_count(), 0);

let r2 = r.activate_cloned();
assert_eq!(r.receiver_count(), 1);
assert_eq!(r.inactive_receiver_count(), 1);

Returns the number of senders for the channel.

Examples
use async_broadcast::broadcast;

let (s, r) = broadcast::<()>(1);
assert_eq!(s.sender_count(), 1);

let s2 = s.clone();
assert_eq!(s.sender_count(), 2);

Downgrade to a InactiveReceiver.

An inactive receiver is one that can not and does not receive any messages. Its only purpose is keep the associated channel open even when there are no (active) receivers. An inactive receiver can be upgraded into a Receiver using InactiveReceiver::activate or InactiveReceiver::activate_cloned.

Sender::try_broadcast will return TrySendError::Inactive if only inactive receivers exists for the associated channel and Sender::broadcast will wait until an active receiver is available.

Examples
use async_broadcast::{broadcast, TrySendError};

let (s, r) = broadcast(1);
let inactive = r.deactivate();
assert_eq!(s.try_broadcast(10), Err(TrySendError::Inactive(10)));

let mut r = inactive.activate();
assert_eq!(s.broadcast(10).await, Ok(None));
assert_eq!(r.recv().await, Ok(10));

Receives a message from the channel.

If the channel is empty, this method waits until there is a message.

If the channel is closed, this method receives a message or returns an error if there are no more messages.

If this receiver has missed a message (only possible if overflow mode is enabled), then this method returns an error and readjusts its cursor to point to the first available message.

Examples
use async_broadcast::{broadcast, RecvError};

let (s, mut r1) = broadcast(1);
let mut r2 = r1.clone();

assert_eq!(s.broadcast(1).await, Ok(None));
drop(s);

assert_eq!(r1.recv().await, Ok(1));
assert_eq!(r1.recv().await, Err(RecvError::Closed));
assert_eq!(r2.recv().await, Ok(1));
assert_eq!(r2.recv().await, Err(RecvError::Closed));

Attempts to receive a message from the channel.

If the channel is empty or closed, this method returns an error.

If this receiver has missed a message (only possible if overflow mode is enabled), then this method returns an error and readjusts its cursor to point to the first available message.

Examples
use async_broadcast::{broadcast, TryRecvError};

let (s, mut r1) = broadcast(1);
let mut r2 = r1.clone();
assert_eq!(s.broadcast(1).await, Ok(None));

assert_eq!(r1.try_recv(), Ok(1));
assert_eq!(r1.try_recv(), Err(TryRecvError::Empty));
assert_eq!(r2.try_recv(), Ok(1));
assert_eq!(r2.try_recv(), Err(TryRecvError::Empty));

drop(s);
assert_eq!(r1.try_recv(), Err(TryRecvError::Closed));
assert_eq!(r2.try_recv(), Err(TryRecvError::Closed));

Produce a new Sender for this channel.

This will not re-open the channel if it was closed due to all senders being dropped.

Examples
use async_broadcast::{broadcast, RecvError};

let (s1, mut r) = broadcast(2);

assert_eq!(s1.broadcast(1).await, Ok(None));

let mut s2 = r.new_sender();

assert_eq!(s2.broadcast(2).await, Ok(None));
drop(s1);
drop(s2);

assert_eq!(r.recv().await, Ok(1));
assert_eq!(r.recv().await, Ok(2));
assert_eq!(r.recv().await, Err(RecvError::Closed));

Produce a new Receiver for this channel.

Unlike Receiver::clone, this method creates a new receiver that starts with zero messages available. This is slightly faster than a real clone.

Examples
use async_broadcast::{broadcast, RecvError};

let (s, mut r1) = broadcast(2);

assert_eq!(s.broadcast(1).await, Ok(None));

let mut r2 = r1.new_receiver();

assert_eq!(s.broadcast(2).await, Ok(None));
drop(s);

assert_eq!(r1.recv().await, Ok(1));
assert_eq!(r1.recv().await, Ok(2));
assert_eq!(r1.recv().await, Err(RecvError::Closed));

assert_eq!(r2.recv().await, Ok(2));
assert_eq!(r2.recv().await, Err(RecvError::Closed));

Trait Implementations

Produce a clone of this Receiver that has the same messages queued.

Examples
use async_broadcast::{broadcast, RecvError};

let (s, mut r1) = broadcast(1);

assert_eq!(s.broadcast(1).await, Ok(None));
drop(s);

let mut r2 = r1.clone();

assert_eq!(r1.recv().await, Ok(1));
assert_eq!(r1.recv().await, Err(RecvError::Closed));
assert_eq!(r2.recv().await, Ok(1));
assert_eq!(r2.recv().await, Err(RecvError::Closed));

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Returns true if the stream should no longer be polled.

Values yielded by the stream.

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more

Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type of successful values yielded by this future

The type of failures yielded by this future

Poll this TryStream as if it were a Stream. Read more