actor_lite/thread_actor.rs
1//! 线程壳:把 actor 跑在一条独占的 `std::thread` 上。
2//!
3//! 和异步壳的区别只有两点:`run` 是阻塞签名、启动方式是 `std::thread`。
4//! 通道、状态、事件、取消的语义完全一致(共用 `core`)。
5
6use std::time::Duration;
7use std::{panic::AssertUnwindSafe, time::Instant};
8
9use tracing::{error, trace};
10
11use crate::core::{ActorContext, ActorCore, ActorHandle, AliveGuard};
12use crate::wait;
13/// actor 的**线程壳**。允许 `!Send` 的资源(GPU 句柄、`Rc<RefCell<_>>`、阻塞式第三方库)。
14///
15/// 不用 `Send`:整个 actor 只会被搬到一条新线程的栈上,从不跨线程移动。
16pub trait ThreadActor: ActorCore {
17 /// actor 的主循环,**阻塞**签名。
18 ///
19 /// 典型写法:
20 ///
21 /// ```no_run
22 /// # use std::time::Duration;
23 /// # use actor_lite::{ActorContext, ActorCore, CmdWait, ThreadActor};
24 /// # struct Player;
25 /// # impl ActorCore for Player {
26 /// # type Cmd = (); type Event = (); type State = (); type Progress = ();
27 /// # fn init_state_and_progress(&self) -> ((), ()) { ((), ()) }
28 /// # }
29 /// impl ThreadActor for Player {
30 /// fn run(self, mut ctx: ActorContext<Self>) {
31 /// loop {
32 /// match ctx.recv_cmd_timeout(Duration::from_millis(8)) {
33 /// Ok(_cmd) => { /* 处理命令 */ }
34 /// Err(CmdWait::Timeout) => { /* 周期性工作:出帧 / 上报进度 */ }
35 /// Err(CmdWait::Closed) => break, // stop() 或所有 handle 都没了
36 /// _ => break, // CmdWait 是 non_exhaustive,留个兜底
37 /// }
38 /// }
39 /// }
40 /// }
41 /// ```
42 fn run(self, ctx: ActorContext<Self>);
43
44 /// 在一条新线程上启动 actor,返回控制端。
45 ///
46 /// **只对 `Send` 的 actor 可用。** `!Send` 的 actor(`Rc<...>`、GPU 句柄、
47 /// 阻塞式第三方运行时)不能这样起 —— 实例没法搬进 `std::thread` 的闭包
48 /// (`error[E0277]: cannot be sent between threads safely`),
49 /// 请改用 [`spawn_thread`] 传**工厂**,让 actor 在新线程内部构造。
50 ///
51 /// ```no_run
52 /// # use actor_lite::{ActorContext, ActorCore, ThreadActor};
53 /// # struct Worker;
54 /// # impl ActorCore for Worker {
55 /// # type Cmd = (); type Event = (); type State = (); type Progress = ();
56 /// # fn init_state_and_progress(&self) -> ((), ()) { ((), ()) }
57 /// # }
58 /// # impl ThreadActor for Worker {
59 /// # fn run(self, _ctx: ActorContext<Self>) {}
60 /// # }
61 /// // Worker 是 Send(没有 Rc 之类)→ 可以直接用方法形式
62 /// let handle = Worker.spawn_thread("worker");
63 /// handle.stop();
64 /// ```
65 fn spawn_thread(self, name: &str) -> ActorHandle<Self>
66 where
67 Self: Send + 'static,
68 {
69 spawn_thread(name, move || self)
70 }
71}
72/// 在一条新线程上启动 actor。
73///
74/// # 为什么是工厂而不是实例
75///
76/// `!Send` 的 actor 无法被搬进 `std::thread` 的闭包(`E0277`),所以 actor 必须在
77/// 新线程内部**构造**。传给闭包的只有构造它所需的数据,那些必须是 `Send`。
78///
79/// ```text
80/// 主线程 新线程
81/// spawn_thread(name, f) → let actor = f(); ← !Send 资源在这里出生
82/// ctx/handle 建好
83/// recv(handle) ←──────────── handle 回传
84/// ```
85///
86/// 返回前会阻塞等 handle 回传(μs 级),所以返回的 handle 一定带着初始化好的 state。
87///
88/// 如果你的 actor 是 `Send` 的,也可以用更顺手的方法形式:[`ThreadActor::spawn_thread`]。
89///
90/// # Panic
91///
92/// 启动失败会 panic(`expect`),需要优雅处理请改用 [`try_spawn_thread`]。
93/// `run` 里的 panic **不会**传播:被 `catch_unwind` 兜住,只记一条 error 日志,
94/// 之后 [`ActorHandle::is_alive`] 变 `false`、`send_cmd` 返回 `Err`。
95/// 这里的 `false` 表示**actor 字段也已经析构完**(panic 展开同样会 drop actor),
96/// 所以拿到 `false` 就可以安全退出进程或重建。
97pub fn spawn_thread<A, F>(name: &str, factory: F) -> ActorHandle<A>
98where
99 A: ThreadActor + 'static,
100 F: FnOnce() -> A + Send + 'static,
101{
102 try_spawn_thread(name, factory).expect("failed to start thread actor")
103}
104
105/// 启动时最多等多久让 actor 交出 handle。超过就判定"构造阶段卡住了"。
106pub const STARTUP_TIMEOUT: Duration = Duration::from_secs(5);
107
108/// 线程 actor 启动失败的原因。
109#[derive(Debug)]
110#[non_exhaustive]
111pub enum SpawnError {
112 /// `std::thread` 建不出来(线程数耗尽、资源不足、名字不合法)。
113 Thread(std::io::Error),
114 /// 构造函数或 `init_state_and_progress` panic 了(含 panic 消息)。
115 ConstructorPanicked(String),
116 /// 构造阶段超过 [`STARTUP_TIMEOUT`] 还没交出 handle(初始化卡住了)。
117 StartupTimeout(Duration),
118}
119
120impl std::fmt::Display for SpawnError {
121 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
122 match self {
123 Self::Thread(e) => write!(f, "failed to spawn actor thread: {e}"),
124 Self::ConstructorPanicked(msg) => write!(f, "actor failed to start: {msg}"),
125 Self::StartupTimeout(d) => {
126 write!(f, "actor did not hand over its handle within {d:?}")
127 }
128 }
129 }
130}
131
132impl std::error::Error for SpawnError {
133 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
134 match self {
135 Self::Thread(e) => Some(e),
136 _ => None,
137 }
138 }
139}
140
141/// 在一条新线程上启动 actor,失败时返回 [`SpawnError`] 而不是 panic。
142///
143/// GUI/服务器这类"不能让一个 actor 起不来就拖垮整个程序"的场景用这个,
144/// 其余情况用 [`spawn_thread`] 更省事。
145///
146/// # 为什么是工厂而不是实例
147///
148/// `!Send` 的 actor 无法被搬进 `std::thread` 的闭包(`error[E0277]`),所以 actor 必须
149/// 在新线程内部**构造**。传给闭包的只有构造它所需的数据,那些必须是 `Send`。
150///
151/// # 错误分类
152///
153/// - [`SpawnError::ConstructorPanicked`]:构造函数或初始化 panic(多为环境问题:
154/// 文件打不开、驱动不兼容、设备被占用)—— **值得展示给用户**;
155/// - [`SpawnError::StartupTimeout`]:初始化卡住;
156/// - [`SpawnError::Thread`]:系统级失败,通常只记日志。
157pub fn try_spawn_thread<A, F>(name: &str, factory: F) -> Result<ActorHandle<A>, SpawnError>
158where
159 A: ThreadActor + 'static,
160 F: FnOnce() -> A + Send + 'static,
161{
162 let thread_name = name.to_owned();
163 let (handle_tx, handle_rx) = std::sync::mpsc::channel::<Result<ActorHandle<A>, SpawnError>>();
164
165 std::thread::Builder::new()
166 .name(thread_name.clone())
167 .spawn(move || {
168 // ① 构造:把 panic 变成可回传的错误,而不是让线程静默死掉
169 let actor = match std::panic::catch_unwind(AssertUnwindSafe(factory)) {
170 Ok(actor) => actor,
171 Err(payload) => {
172 let _ = handle_tx.send(Err(SpawnError::ConstructorPanicked(panic_message(
173 &*payload,
174 ))));
175 return;
176 }
177 };
178
179 let (init_state, init_progress) = match std::panic::catch_unwind(AssertUnwindSafe(
180 || actor.init_state_and_progress(),
181 )) {
182 Ok(v) => v,
183 Err(payload) => {
184 let _ = handle_tx.send(Err(SpawnError::ConstructorPanicked(panic_message(
185 &*payload,
186 ))));
187 return;
188 }
189 };
190
191 let (mut ctx, handle) = A::channel(init_state, init_progress);
192 // ★ 守卫移出 ctx,由闭包持有 —— 它会在闭包最后才 drop
193 let alive = ctx.take_alive_guard();
194 // 点亮 waker:之后 send_cmd / stop 就能 unpark 这条线程
195 handle.attach_current_thread();
196
197 if handle_tx.send(Ok(handle)).is_err() {
198 return; // 调用方已经放弃等待
199 }
200
201 trace!(
202 actor = std::any::type_name::<A>(),
203 thread = %thread_name,
204 "thread actor started"
205 );
206
207 // ② 运行:panic 也不能拖垮进程
208 if let Err(payload) = std::panic::catch_unwind(AssertUnwindSafe(|| actor.run(ctx))) {
209 error!(
210 actor = std::any::type_name::<A>(),
211 panic = %panic_message(&*payload),
212 "thread actor panicked"
213 );
214 };
215 drop(alive);
216 })
217 .map_err(SpawnError::Thread)?;
218
219 match handle_rx.recv_timeout(STARTUP_TIMEOUT) {
220 Ok(result) => result,
221 Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
222 Err(SpawnError::StartupTimeout(STARTUP_TIMEOUT))
223 }
224 Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => Err(
225 // 线程在交出 handle 之前就死了(上面两条 catch_unwind 之外的路径)
226 SpawnError::ConstructorPanicked("actor thread died during startup".to_owned()),
227 ),
228 }
229}
230
231/// 从 `catch_unwind` 的 payload 里取出可读信息。
232fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
233 payload
234 .downcast_ref::<&str>()
235 .map(|s| (*s).to_owned())
236 .or_else(|| payload.downcast_ref::<String>().cloned())
237 .unwrap_or_else(|| "<non-string panic payload>".to_owned())
238}
239
240/// [`ActorContext::recv_cmd_timeout`](crate::thread_actor::ActorContext::recv_cmd_timeout) 的等待结果。
241/// `Timeout` 不是错误,是正常的空闲 tick。
242#[derive(Debug, Clone, Copy, PartialEq, Eq)]
243#[non_exhaustive]
244pub enum CmdWait {
245 /// 这段时间内没有命令。
246 Timeout,
247 /// actor 已停止,或命令通道关闭 —— 该退出循环了。
248 Closed,
249}
250
251impl<A: ThreadActor> ActorHandle<A> {
252 /// 只在 `spawn_thread` 里调用:把共享 waker 绑定到调用线程。
253 pub(crate) fn attach_current_thread(&self) {
254 self.waker.attach_current();
255 }
256}
257
258impl<A: ThreadActor> ActorContext<A> {
259 /// 阻塞等待下一条命令,最多等 `dur`。会把当前线程 park 住。
260 ///
261 /// 有命令 → `Ok(cmd)`;`dur` 内无命令 → `Err(CmdWait::Timeout)`;
262 /// 已停止/通道关闭 → `Err(CmdWait::Closed)`。会被 `send_cmd` / `stop` 提前唤醒。
263 /// 传 `Duration::MAX` 等价于无限等待。
264 pub fn recv_cmd_timeout(&mut self, dur: Duration) -> Result<A::Cmd, CmdWait> {
265 if self.cancel.is_cancelled() {
266 return Err(CmdWait::Closed);
267 }
268 let waker = self.waker.waker();
269 let deadline = Instant::now().checked_add(dur);
270 // 两个字段分别可变/不可变借用 → 合法
271 let cmd_fut = self.cmd_rx.recv();
272 let cancel_fut = self.cancel.cancelled();
273
274 match wait::drive_either(cmd_fut, cancel_fut, deadline, &waker) {
275 Some(wait::Either2::First(Some(cmd))) => Ok(cmd),
276 Some(wait::Either2::First(None)) => Err(CmdWait::Closed), // 所有 handle 都没了
277 Some(wait::Either2::Second(())) => Err(CmdWait::Closed), // 被 stop()
278 None => Err(CmdWait::Timeout),
279 }
280 }
281 /// 一直阻塞到有命令、或 actor 被停止。
282 pub fn recv_cmd(&mut self) -> Option<A::Cmd> {
283 match self.recv_cmd_timeout(Duration::MAX) {
284 Ok(cmd) => Some(cmd),
285 Err(CmdWait::Closed) => None,
286 Err(CmdWait::Timeout) => unreachable!("无限等待不会超时"),
287 }
288 }
289 /// 把存活守卫从 ctx 里拿出来,交给线程闭包持有。
290 ///
291 /// 这是 0.1.1 修复的核心:守卫必须在线程闭包的**最后**才 drop ——
292 /// 也就是在 `actor.run(ctx)` 消费掉 actor、其字段(设备 / 解码器 / 字体库)
293 /// 析构完之后。留在 ctx 里会早一个窗口,见 [`AliveGuard`] 的注释。
294 fn take_alive_guard(&mut self) -> Option<AliveGuard> {
295 self._alive.take()
296 }
297}