pub struct Sender<T> { /* private fields */ }
Expand description
Sends a value to the associated Receiver
.
A pair of both a Sender
and a Receiver
are created by the
channel
function.
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 Sender
from a destructor, put it in an Option
and call
Option::take
.
use tokio::sync::oneshot;
struct SendOnDrop {
sender: Option<oneshot::Sender<&'static str>>,
}
impl Drop for SendOnDrop {
fn drop(&mut self) {
if let Some(sender) = self.sender.take() {
// Using `let _ =` to ignore send errors.
let _ = sender.send("I got dropped!");
}
}
}
#[tokio::main]
async fn main() {
let (send, recv) = oneshot::channel();
let send_on_drop = SendOnDrop { sender: Some(send) };
drop(send_on_drop);
assert_eq!(recv.await, Ok("I got dropped!"));
}
Implementations
sourceimpl<T> Sender<T>
impl<T> Sender<T>
sourcepub fn send(self, t: T) -> Result<(), T>
pub fn send(self, t: T) -> Result<(), T>
Attempts to send a value on this channel, returning it back if it could not be sent.
This method consumes self
as only one value may ever be sent on a oneshot
channel. It is not marked async because sending a message to an oneshot
channel never requires any form of waiting. Because of this, the send
method can be used in both synchronous and asynchronous code without
problems.
A successful send occurs when it is determined that the other end of the
channel has not hung up already. An unsuccessful send would be one where
the corresponding receiver has already been deallocated. Note that a
return value of Err
means that the data will never be received, but
a return value of Ok
does not mean that the data will be received.
It is possible for the corresponding receiver to hang up immediately
after this function returns Ok
.
Examples
Send a value to another task
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"),
}
}
sourcepub async fn closed(&mut self)
pub async fn closed(&mut self)
Waits for the associated Receiver
handle to close.
A Receiver
is closed by either calling close
explicitly or the
Receiver
value is dropped.
This function is useful when paired with select!
to abort a
computation when the receiver is no longer interested in the result.
Return
Returns a Future
which must be awaited on.
Examples
Basic usage
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (mut tx, rx) = oneshot::channel::<()>();
tokio::spawn(async move {
drop(rx);
});
tx.closed().await;
println!("the receiver dropped");
}
Paired with select
use tokio::sync::oneshot;
use tokio::time::{self, Duration};
async fn compute() -> String {
// Complex computation returning a `String`
}
#[tokio::main]
async fn main() {
let (mut tx, rx) = oneshot::channel();
tokio::spawn(async move {
tokio::select! {
_ = tx.closed() => {
// The receiver dropped, no need to do any further work
}
value = compute() => {
// The send can fail if the channel was closed at the exact same
// time as when compute() finished, so just ignore the failure.
let _ = tx.send(value);
}
}
});
// Wait for up to 10 seconds
let _ = time::timeout(Duration::from_secs(10), rx).await;
}
sourcepub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
Returns true
if the associated Receiver
handle has been dropped.
A Receiver
is closed by either calling close
explicitly or the
Receiver
value is dropped.
If true
is returned, a call to send
will always result in an error.
Examples
use tokio::sync::oneshot;
#[tokio::main]
async fn main() {
let (tx, rx) = oneshot::channel();
assert!(!tx.is_closed());
drop(rx);
assert!(tx.is_closed());
assert!(tx.send("never received").is_err());
}
sourcepub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll<()>
pub fn poll_closed(&mut self, cx: &mut Context<'_>) -> Poll<()>
Checks whether the oneshot channel has been closed, and if not, schedules the
Waker
in the provided Context
to receive a notification when the channel is
closed.
A Receiver
is closed by either calling close
explicitly, or when the
Receiver
value is dropped.
Note that on multiple calls to poll, only the Waker
from the Context
passed
to the most recent call will be scheduled to receive a wakeup.
Return value
This function returns:
Poll::Pending
if the channel is still open.Poll::Ready(())
if the channel is closed.
Examples
use tokio::sync::oneshot;
use futures::future::poll_fn;
#[tokio::main]
async fn main() {
let (mut tx, mut rx) = oneshot::channel::<()>();
tokio::spawn(async move {
rx.close();
});
poll_fn(|cx| tx.poll_closed(cx)).await;
println!("the receiver dropped");
}
Trait Implementations
Auto Trait Implementations
impl<T> !RefUnwindSafe for Sender<T>
impl<T> Send for Sender<T> where
T: Send,
impl<T> Sync for Sender<T> where
T: Send,
impl<T> Unpin for Sender<T>
impl<T> !UnwindSafe for Sender<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