pub struct Receiver<T> { /* private fields */ }
Expand description
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
sourceimpl<T: Clone> Receiver<T>
impl<T: Clone> Receiver<T>
sourcepub async fn recv(&mut self) -> Result<T, RecvError>
pub async fn recv(&mut self) -> Result<T, RecvError>
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.
Cancel safety
This method is cancel safe. If recv
is used as the event in a
tokio::select!
statement and some other branch
completes first, it is guaranteed that no messages were received on this
channel.
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());
}
sourcepub fn try_recv(&mut self) -> Result<T, TryRecvError>
pub fn try_recv(&mut self) -> Result<T, TryRecvError>
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: Send> Send for Receiver<T>
impl<T: Send> Sync for Receiver<T>
Auto Trait Implementations
impl<T> !RefUnwindSafe for Receiver<T>
impl<T> Unpin for Receiver<T>
impl<T> !UnwindSafe for Receiver<T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more