Skip to main content

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}