Skip to main content

wordval_utils/
task_handle.rs

1//! 异步任务句柄托管:自动清理已完成任务、统一 abort 收口
2//!
3//! 插件与后台服务常散落 `tokio::spawn` 的句柄管理:裸 `Vec<JoinHandle>`
4//! 会随时间无限增长(已完成任务不被移除),停机时也没有统一的 abort 入口。
5//! [`TaskHandles`] 提供:
6//!
7//! - [`push`](TaskHandles::push):入队时顺带清理已完成句柄,内存有界;
8//! - [`abort_all`](TaskHandles::abort_all):停机时一次性中止全部任务;
9//! - [`all_finished`](TaskHandles::all_finished):观测全部任务是否自然结束。
10//!
11//! ```rust
12//! use wordval_utils::task_handle::TaskHandles;
13//!
14//! # async fn demo() {
15//! let handles = TaskHandles::default();
16//! handles.push(tokio::spawn(async { /* 后台工作 */ }));
17//! handles.abort_all();
18//! # }
19//! ```
20
21use std::sync::Mutex;
22use tokio::task::JoinHandle;
23
24/// 异步任务句柄集合(不施加 spawn/join 策略,只管存取与清理)
25#[derive(Debug, Default)]
26pub struct TaskHandles {
27    handles: Mutex<Vec<JoinHandle<()>>>,
28}
29
30impl TaskHandles {
31    /// 存入句柄;顺带移除已完成的句柄(内存有界)
32    pub fn push(&self, handle: JoinHandle<()>) {
33        let mut handles = self.handles.lock().unwrap();
34        handles.retain(|h| !h.is_finished());
35        handles.push(handle);
36    }
37
38    /// 取出并 abort 全部句柄
39    pub fn abort_all(&self) {
40        for handle in self.take_all() {
41            handle.abort();
42        }
43    }
44
45    /// 原地 abort 全部句柄但不移除记录——调用方稍后可用
46    /// [`Self::all_finished`] 等待其真正终止
47    pub fn abort_all_retained(&self) {
48        for handle in self.handles.lock().unwrap().iter() {
49            handle.abort();
50        }
51    }
52
53    /// 取出全部句柄(此后集合为空)
54    pub fn take_all(&self) -> Vec<JoinHandle<()>> {
55        std::mem::take(&mut *self.handles.lock().unwrap())
56    }
57
58    /// 全部已记录任务是否都已结束
59    pub fn all_finished(&self) -> bool {
60        self.handles
61            .lock()
62            .unwrap()
63            .iter()
64            .all(JoinHandle::is_finished)
65    }
66
67    /// 当前记录的任务数(含未清理的已完成任务)
68    pub fn len(&self) -> usize {
69        self.handles.lock().unwrap().len()
70    }
71
72    /// 是否没有记录任何任务
73    pub fn is_empty(&self) -> bool {
74        self.len() == 0
75    }
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81    use std::sync::Arc;
82    use std::time::Duration;
83
84    #[tokio::test]
85    async fn push_cleans_finished_handles() {
86        let handles = TaskHandles::default();
87        handles.push(tokio::spawn(async {})); // 立即完成
88        // 让出调度,确保任务结束
89        tokio::time::sleep(Duration::from_millis(10)).await;
90        handles.push(tokio::spawn(async {})); // push 时清理掉前一个
91        tokio::time::sleep(Duration::from_millis(10)).await;
92        assert_eq!(handles.len(), 1, "已完成句柄应被 push 顺带清理");
93    }
94
95    #[tokio::test]
96    async fn abort_all_stops_tasks() {
97        let handles = TaskHandles::default();
98        let guard = Arc::new(tokio::sync::Notify::new());
99        let g = guard.clone();
100        handles.push(tokio::spawn(async move {
101            // 长任务:若不被 abort 则 notify
102            tokio::time::sleep(Duration::from_secs(60)).await;
103            g.notify_one();
104        }));
105        handles.abort_all();
106        tokio::time::sleep(Duration::from_millis(50)).await;
107        assert!(handles.all_finished());
108    }
109
110    #[tokio::test]
111    async fn take_all_empties() {
112        let handles = TaskHandles::default();
113        handles.push(tokio::spawn(async {}));
114        assert_eq!(handles.take_all().len(), 1);
115        assert!(handles.is_empty());
116    }
117}