Struct Sender

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 a 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;

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"),
}

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;

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`
}

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;

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;

let (tx, rx) = oneshot::channel();

assert!(!tx.is_closed());

drop(rx);

assert!(tx.is_closed());
assert!(tx.send("never received").is_err());

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 std::future::poll_fn;

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");

Returns the argument unchanged.

Calls U::from(self).

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