pub struct Receiver<T> { /* private fields */ }
Expand description
Receives a value from the associated Sender
.
A pair of both a Sender
and a Receiver
are created by the
channel
function.
This channel has no recv
method because the receiver itself implements the
Future
trait. To receive a value, .await
the Receiver
object directly.
Examples
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (tx, rx) = oneshot::channel();
tokio::spawn(async move {
if let Err(_) = tx.send(3) {
println!("the receiver dropped");
}
});
match rx.await {
Ok(v) => println!("got = {:?}", v),
Err(_) => println!("the sender dropped"),
}
}
If the sender is dropped without sending, the receiver will fail with
error::RecvError
:
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (tx, rx) = oneshot::channel::<u32>();
tokio::spawn(async move {
drop(tx);
});
match rx.await {
Ok(_) => panic!("This doesn't happen"),
Err(_) => println!("the sender dropped"),
}
}
To use a Receiver
in a tokio::select!
loop, add &mut
in front of the
channel.
use tokio::sync::oneshot;
use tokio::time::{interval, sleep, Duration};
#[tokio::main]
async fn main() {
let (send, mut recv) = oneshot::channel();
let mut interval = interval(Duration::from_millis(100));
tokio::spawn(async move {
sleep(Duration::from_secs(1)).await;
send.send("shut down").unwrap();
});
loop {
tokio::select! {
_ = interval.tick() => println!("Another 100ms"),
msg = &mut recv => {
println!("Got message: {}", msg.unwrap());
break;
}
}
}
}
Implementations
sourceimpl<T> Receiver<T>
impl<T> Receiver<T>
sourcepub fn close(&mut self)
pub fn close(&mut self)
Prevents the associated Sender
handle from sending a value.
Any send
operation which happens after calling close
is guaranteed
to fail. After calling close
, try_recv
should be called to
receive a value if one was sent before the call to close
completed.
This function is useful to perform a graceful shutdown and ensure that a value will not be sent into the channel and never received.
close
is no-op if a message is already received or the channel
is already closed.
Examples
Prevent a value from being sent
use tokio::sync::oneshot;
use tokio::sync::oneshot::error::TryRecvError;
#[tokio::main]
async fn main() {
let (tx, mut rx) = oneshot::channel();
assert!(!tx.is_closed());
rx.close();
assert!(tx.is_closed());
assert!(tx.send("never received").is_err());
match rx.try_recv() {
Err(TryRecvError::Closed) => {}
_ => unreachable!(),
}
}
Receive a value sent before calling close
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (tx, mut rx) = oneshot::channel();
assert!(tx.send("will receive").is_ok());
rx.close();
let msg = rx.try_recv().unwrap();
assert_eq!(msg, "will receive");
}
sourcepub fn try_recv(&mut self) -> Result<T, TryRecvError>
pub fn try_recv(&mut self) -> Result<T, TryRecvError>
Attempts to receive a value.
If a pending value exists in the channel, it is returned. If no value has been sent, the current task will not be registered for future notification.
This function is useful to call from outside the context of an asynchronous task.
Return
Ok(T)
if a value is pending in the channel.Err(TryRecvError::Empty)
if no value has been sent yet.Err(TryRecvError::Closed)
if the sender has dropped without sending a value.
Examples
try_recv
before a value is sent, then after.
use tokio::sync::oneshot;
use tokio::sync::oneshot::error::TryRecvError;
#[tokio::main]
async fn main() {
let (tx, mut rx) = oneshot::channel();
match rx.try_recv() {
// The channel is currently empty
Err(TryRecvError::Empty) => {}
_ => unreachable!(),
}
// Send a value
tx.send("hello").unwrap();
match rx.try_recv() {
Ok(value) => assert_eq!(value, "hello"),
_ => unreachable!(),
}
}
try_recv
when the sender dropped before sending a value
use tokio::sync::oneshot;
use tokio::sync::oneshot::error::TryRecvError;
#[tokio::main]
async fn main() {
let (tx, mut rx) = oneshot::channel::<()>();
drop(tx);
match rx.try_recv() {
// The channel will never receive a value.
Err(TryRecvError::Closed) => {}
_ => unreachable!(),
}
}
sourcepub fn blocking_recv(self) -> Result<T, RecvError>
pub fn blocking_recv(self) -> Result<T, RecvError>
Blocking receive to call outside of asynchronous contexts.
Panics
This function panics if called within an asynchronous execution context.
Examples
use std::thread;
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (tx, rx) = oneshot::channel::<u8>();
let sync_code = thread::spawn(move || {
assert_eq!(Ok(10), rx.blocking_recv());
});
let _ = tx.send(10);
sync_code.join().unwrap();
}
Trait Implementations
Auto Trait Implementations
impl<T> !RefUnwindSafe for Receiver<T>
impl<T> Send for Receiver<T> where
T: Send,
impl<T> Sync for Receiver<T> where
T: Send,
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
sourceimpl<F> IntoFuture for F where
F: Future,
impl<F> IntoFuture for F where
F: Future,
type Output = <F as Future>::Output
type Output = <F as Future>::Output
into_future
)The output that the future will produce on completion.
type IntoFuture = F
type IntoFuture = F
into_future
)Which kind of future are we turning this into?
sourcefn into_future(self) -> <F as IntoFuture>::IntoFuture
fn into_future(self) -> <F as IntoFuture>::IntoFuture
into_future
)Creates a future from a value.