Rust / 系统课时

使用 oneshot 返回单次结果

使用 oneshot 返回单次结果

tokio::sync::oneshot 用于在两个任务之间交付恰好一个值,最常见的用途是“提交请求后等待这一次结果”。它没有消息队列,也不支持重复发送;真正需要掌握的是发送端、接收端任一方提前退出时,另一方如何得到明确错误。

学习目标

  • 使用 oneshot::channel 在任务间返回一次性结果
  • 区分发送成功、接收端提前关闭和发送端提前释放
  • 理解 Sender::send 与 Receiver::await 的错误值含义

一次性通道的接口规则

oneshot::channel::<T>() 返回 Sender<T> 与 Receiver<T>。Sender::send(value) 是同步方法,会消费发送端本身,因此一个发送端最多发送一次;Receiver 实现了 Future,使用 .await 等待结果。

这类通道特别适合请求与响应配对:调用方创建通道,把 Sender 随工作请求交给后台任务,然后自己持有 Receiver 等待该工作的唯一结果。它不适合事件流、任务队列或多次状态更新,这些场景应使用 mpsc、broadcast 或 watch 等原语。

主示例与三种结果

下面的程序先演示正常返回,再分别制造“接收端先消失”和“发送端未发送就消失”。一个示例即可把双方的错误边界看清。

Cargo.toml:

toml
[package]
name = "oneshot-demo"
version = "0.1.0"
edition = "2024"

[dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread", "sync"] }

src/main.rs:

rust
use tokio::sync::oneshot;

#[tokio::main]
async fn main() {
    let (tx, rx) = oneshot::channel::<String>();

    tokio::spawn(async move {
        let result = "done:42".to_string();

        // send 失败时会把原值交还给发送方。
        if let Err(value) = tx.send(result) {
            println!("receiver dropped, value={value}");
        }
    });

    match rx.await {
        Ok(value) => println!("success: {value}"),
        Err(_) => println!("receive failed"),
    }

    let (tx, rx) = oneshot::channel::<&'static str>();
    drop(rx);
    if let Err(value) = tx.send("late") {
        println!("send failed, value returned: {value}");
    }

    let (tx, rx) = oneshot::channel::<&'static str>();
    drop(tx);
    if rx.await.is_err() {
        println!("receive failed: sender dropped");
    }
}

预期输出

text
success: done:42
send failed, value returned: late
receive failed: sender dropped

正常路径中,工作任务调用 send 后,等待中的接收端得到 Ok(T)。如果接收端已经被释放或显式关闭,send 返回 Err(T),原值不会凭空丢失;发送方可以选择记录、回收或采用其他补偿逻辑。

反过来,如果 Sender 在发送前被释放,Receiver.await 返回 Err(RecvError)。因此等待方不应直接假定一定有结果,而应把“工作任务崩溃、提前返回或主动取消”视为可能的失败来源。

取消与生命周期边界

oneshot 不要求 send 发生在异步上下文中,因为发送本身不需要 .await。接收端等待才是异步操作。若接收方已经不再关心结果,可以释放 Receiver,发送方随后会在 send 时得到原值;也可以显式调用 Receiver::close(),阻止之后的发送。

当后台计算昂贵时,发送方还可以等待 Sender::closed(),在发现接收方已关闭后尽早停止计算。这样能把“调用方已经取消请求”传播到执行任务,而不是继续做一个无人接收的结果。

只要把生命周期责任分清,oneshot 的错误处理就很直接:发送失败检查接收端是否已退出,接收失败检查发送端是否在产出结果前结束。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 oneshot 返回单次结果

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通