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:
[package]
name = "oneshot-demo"
version = "0.1.0"
edition = "2024"
[dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread", "sync"] }src/main.rs:
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");
}
}预期输出
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 的错误处理就很直接:发送失败检查接收端是否已退出,接收失败检查发送端是否在产出结果前结束。