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};
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`。
95pub fn spawn_thread<A, F>(name: &str, factory: F) -> ActorHandle<A>
96where
97 A: ThreadActor + 'static,
98 F: FnOnce() -> A + Send + 'static,
99{
100 try_spawn_thread(name, factory).expect("failed to start thread actor")
101}
102
103/// 启动时最多等多久让 actor 交出 handle。超过就判定"构造阶段卡住了"。
104pub const STARTUP_TIMEOUT: Duration = Duration::from_secs(5);
105
106/// 线程 actor 启动失败的原因。
107#[derive(Debug)]
108#[non_exhaustive]
109pub enum SpawnError {
110 /// `std::thread` 建不出来(线程数耗尽、资源不足、名字不合法)。
111 Thread(std::io::Error),
112 /// 构造函数或 `init_state_and_progress` panic 了(含 panic 消息)。
113 ConstructorPanicked(String),
114 /// 构造阶段超过 [`STARTUP_TIMEOUT`] 还没交出 handle(初始化卡住了)。
115 StartupTimeout(Duration),
116}
117
118impl std::fmt::Display for SpawnError {
119 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
120 match self {
121 Self::Thread(e) => write!(f, "failed to spawn actor thread: {e}"),
122 Self::ConstructorPanicked(msg) => write!(f, "actor failed to start: {msg}"),
123 Self::StartupTimeout(d) => {
124 write!(f, "actor did not hand over its handle within {d:?}")
125 }
126 }
127 }
128}
129
130impl std::error::Error for SpawnError {
131 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
132 match self {
133 Self::Thread(e) => Some(e),
134 _ => None,
135 }
136 }
137}
138
139/// 在一条新线程上启动 actor,失败时返回 [`SpawnError`] 而不是 panic。
140///
141/// GUI/服务器这类"不能让一个 actor 起不来就拖垮整个程序"的场景用这个,
142/// 其余情况用 [`spawn_thread`] 更省事。
143///
144/// # 为什么是工厂而不是实例
145///
146/// `!Send` 的 actor 无法被搬进 `std::thread` 的闭包(`error[E0277]`),所以 actor 必须
147/// 在新线程内部**构造**。传给闭包的只有构造它所需的数据,那些必须是 `Send`。
148///
149/// # 错误分类
150///
151/// - [`SpawnError::ConstructorPanicked`]:构造函数或初始化 panic(多为环境问题:
152/// 文件打不开、驱动不兼容、设备被占用)—— **值得展示给用户**;
153/// - [`SpawnError::StartupTimeout`]:初始化卡住;
154/// - [`SpawnError::Thread`]:系统级失败,通常只记日志。
155pub fn try_spawn_thread<A, F>(name: &str, factory: F) -> Result<ActorHandle<A>, SpawnError>
156where
157 A: ThreadActor + 'static,
158 F: FnOnce() -> A + Send + 'static,
159{
160 let thread_name = name.to_owned();
161 let (handle_tx, handle_rx) = std::sync::mpsc::channel::<Result<ActorHandle<A>, SpawnError>>();
162
163 std::thread::Builder::new()
164 .name(thread_name.clone())
165 .spawn(move || {
166 // ① 构造:把 panic 变成可回传的错误,而不是让线程静默死掉
167 let actor = match std::panic::catch_unwind(AssertUnwindSafe(factory)) {
168 Ok(actor) => actor,
169 Err(payload) => {
170 let _ = handle_tx.send(Err(SpawnError::ConstructorPanicked(panic_message(
171 &*payload,
172 ))));
173 return;
174 }
175 };
176
177 let (init_state, init_progress) = match std::panic::catch_unwind(AssertUnwindSafe(
178 || actor.init_state_and_progress(),
179 )) {
180 Ok(v) => v,
181 Err(payload) => {
182 let _ = handle_tx.send(Err(SpawnError::ConstructorPanicked(panic_message(
183 &*payload,
184 ))));
185 return;
186 }
187 };
188
189 let (ctx, handle) = A::channel(init_state, init_progress);
190
191 // 点亮 waker:之后 send_cmd / stop 就能 unpark 这条线程
192 handle.attach_current_thread();
193
194 if handle_tx.send(Ok(handle)).is_err() {
195 return; // 调用方已经放弃等待
196 }
197
198 trace!(
199 actor = std::any::type_name::<A>(),
200 thread = %thread_name,
201 "thread actor started"
202 );
203
204 // ② 运行:panic 也不能拖垮进程
205 if let Err(payload) = std::panic::catch_unwind(AssertUnwindSafe(|| actor.run(ctx))) {
206 error!(
207 actor = std::any::type_name::<A>(),
208 panic = %panic_message(&*payload),
209 "thread actor panicked"
210 );
211 }
212 })
213 .map_err(SpawnError::Thread)?;
214
215 match handle_rx.recv_timeout(STARTUP_TIMEOUT) {
216 Ok(result) => result,
217 Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
218 Err(SpawnError::StartupTimeout(STARTUP_TIMEOUT))
219 }
220 Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => Err(
221 // 线程在交出 handle 之前就死了(上面两条 catch_unwind 之外的路径)
222 SpawnError::ConstructorPanicked("actor thread died during startup".to_owned()),
223 ),
224 }
225}
226
227/// 从 `catch_unwind` 的 payload 里取出可读信息。
228fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
229 payload
230 .downcast_ref::<&str>()
231 .map(|s| (*s).to_owned())
232 .or_else(|| payload.downcast_ref::<String>().cloned())
233 .unwrap_or_else(|| "<non-string panic payload>".to_owned())
234}
235
236/// [`ActorContext::recv_cmd_timeout`](crate::thread_actor::ActorContext::recv_cmd_timeout) 的等待结果。
237/// `Timeout` 不是错误,是正常的空闲 tick。
238#[derive(Debug, Clone, Copy, PartialEq, Eq)]
239#[non_exhaustive]
240pub enum CmdWait {
241 /// 这段时间内没有命令。
242 Timeout,
243 /// actor 已停止,或命令通道关闭 —— 该退出循环了。
244 Closed,
245}
246
247impl<A: ThreadActor> ActorHandle<A> {
248 /// 只在 `spawn_thread` 里调用:把共享 waker 绑定到调用线程。
249 pub(crate) fn attach_current_thread(&self) {
250 self.waker.attach_current();
251 }
252}
253
254impl<A: ThreadActor> ActorContext<A> {
255 /// 阻塞等待下一条命令,最多等 `dur`。会把当前线程 park 住。
256 ///
257 /// 有命令 → `Ok(cmd)`;`dur` 内无命令 → `Err(CmdWait::Timeout)`;
258 /// 已停止/通道关闭 → `Err(CmdWait::Closed)`。会被 `send_cmd` / `stop` 提前唤醒。
259 /// 传 `Duration::MAX` 等价于无限等待。
260 pub fn recv_cmd_timeout(&mut self, dur: Duration) -> Result<A::Cmd, CmdWait> {
261 if self.cancel.is_cancelled() {
262 return Err(CmdWait::Closed);
263 }
264 let waker = self.waker.waker();
265 let deadline = Instant::now().checked_add(dur);
266 // 两个字段分别可变/不可变借用 → 合法
267 let cmd_fut = self.cmd_rx.recv();
268 let cancel_fut = self.cancel.cancelled();
269
270 match wait::drive_either(cmd_fut, cancel_fut, deadline, &waker) {
271 Some(wait::Either2::First(Some(cmd))) => Ok(cmd),
272 Some(wait::Either2::First(None)) => Err(CmdWait::Closed), // 所有 handle 都没了
273 Some(wait::Either2::Second(())) => Err(CmdWait::Closed), // 被 stop()
274 None => Err(CmdWait::Timeout),
275 }
276 }
277 /// 一直阻塞到有命令、或 actor 被停止。
278 pub fn recv_cmd(&mut self) -> Option<A::Cmd> {
279 match self.recv_cmd_timeout(Duration::MAX) {
280 Ok(cmd) => Some(cmd),
281 Err(CmdWait::Closed) => None,
282 Err(CmdWait::Timeout) => unreachable!("无限等待不会超时"),
283 }
284 }
285}