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};
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}