Struct Sender

pub struct Sender<T> { /* private fields */ }

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

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

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

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());
}

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 std::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

impl<T> Debug for Sender<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Drop for Sender<T>

fn drop(&mut self)

Executes the destructor for this type.