Skip to main content

wordval_actor/
system.rs

1//! ActorSystem —— 命名注册表、监督者与优雅关闭。
2//!
3//! 设计要点:
4//! - **命名寻址**:[`DashMap`] 分片注册表,重名 spawn 返回
5//!   [`ActorError::DuplicateName`](绝不静默顶替,杜绝孤儿任务)。
6//! - **类型擦除仅限冷路径**:调用方持有类型化 [`ActorRef`];注册表条目
7//!   只保存信号投递 / 停止所需的擦除句柄。
8//! - **监督**:事件循环 panic 被任务边界捕获,按
9//!   [`RestartPolicy`] 指数退避重启;终止(无论原因)向全部 watch 者
10//!   发送 [`ActorSignal::Terminated`]。
11//! - **信号专用通道**:系统信号与看门狗触发标记走独立于用户邮箱的
12//!   小容量通道,事件循环每轮优先抽干 —— Terminated 通知与失控保护
13//!   触发都不被消息积压阻塞。
14//! - **可重启关闭**:`shutdown` 幂等,等待全部 Actor 真正退出;
15//!   并发调用时仅首个调用者执行关闭流程,其余立即返回(可能先于
16//!   关闭完成);插件 stop → start 会重建全新系统(无 OnceLock 毒化)。
17
18use crate::addr::{ActorId, ActorName};
19use crate::actor::{Actor, ActorAction};
20use crate::ctx::ActorContext;
21use crate::mailbox::{latest_slot, SlotReader, DEFAULT_MAILBOX_CAPACITY};
22use crate::msg::{
23    ActorMsg, ActorPhase, ActorSignal, Signal, StopCause, Terminated, publish_phase, request_stop,
24};
25use crate::refs::{new_ref, ActorRef};
26use crate::timer::{Clock, ClockSource, TimerDriver, deadline_after};
27use dashmap::DashMap;
28use std::fmt;
29use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering as AtomicOrdering};
30use std::sync::Arc;
31use std::time::Duration;
32use tokio::sync::{mpsc, oneshot, watch};
33
34/// 每轮事件循环从控制通道批量抽取的消息上限(摊薄唤醒调度开销)。
35const SELF_BATCH_LIMIT: usize = 64;
36
37tokio::task_local! {
38    /// 「当前正在执行哪个 Actor 的世代事件循环」标记。
39    ///
40    /// 仅覆盖世代任务自身的执行链(`on_start` / `handle` / `on_signal` /
41    /// `on_stop` 及其中内联的 await),**不会**传播到该任务 `tokio::spawn`
42    /// 出的子任务 —— 经子任务转手的自调用不在检测范围内,需调用方自行避免。
43    pub(crate) static GENERATION_ACTOR: ActorId;
44}
45
46/// 自调用防护:在「必须等待目标 Actor 自身推进」的阻塞式 API 入口调用。
47///
48/// # Panics
49///
50/// 当且仅当调用发生在 `target` 自己的世代任务内时 panic —— 这类调用等待
51/// 由目标事件循环产生的进展,而事件循环正阻塞在该调用上,必然死锁或等满
52/// 超时;立即以明确诊断失败优于静默挂起。panic 由世代任务边界捕获,按
53/// 监督策略处置(重启或终止并通知 watchers)。
54pub(crate) fn assert_not_self_call(target: ActorId, what: &str) {
55    if let Ok(caller) = GENERATION_ACTOR.try_with(|id| *id) {
56        assert_ne!(
57            caller, target,
58            "检测到 Actor {target} 的 {what} 自调用:该 API 需等待目标事件循环\
59             推进,而事件循环正阻塞在此调用上,必然死锁或等满超时。\
60             请求自身停止请改用 ActorContext::stop() 并返回 ActorAction::Stop;\
61             确有异步需要时请在 tokio::spawn 出的独立任务中调用\
62             (子任务不带世代身份,不在本检测范围内)"
63        );
64    }
65}
66
67/// Actor 系统错误。
68#[derive(Debug, Clone, PartialEq, Eq)]
69pub enum ActorError {
70    /// 名称已被占用。
71    DuplicateName(ActorName),
72    /// 目标邮箱已满(有界背压),调用方应稍后重试或降载。
73    MailboxFull(ActorId),
74    /// 目标通道已关闭。
75    Closed(ActorId),
76    /// 停止请求已送达,但 Actor 未在期限内退出
77    /// (见 [`stop_and_wait_timeout`](ActorSystem::stop_and_wait_timeout))。
78    Timeout(ActorId),
79    /// 系统已 [`shutdown`](ActorSystem::shutdown),拒绝新 spawn。
80    SystemShutdown,
81}
82
83impl fmt::Display for ActorError {
84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85        match self {
86            ActorError::DuplicateName(n) => write!(f, "Actor 名称 \"{n}\" 已被占用"),
87            ActorError::MailboxFull(id) => write!(f, "Actor {id} 邮箱已满,请稍后重试"),
88            ActorError::Closed(id) => write!(f, "Actor {id} 通道已关闭"),
89            ActorError::Timeout(id) => write!(f, "Actor {id} 未在期限内退出"),
90            ActorError::SystemShutdown => f.write_str("ActorSystem 已关闭"),
91        }
92    }
93}
94
95impl std::error::Error for ActorError {}
96
97/// 监督策略 —— 决定事件循环 panic 后的处置。
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
99pub enum RestartPolicy {
100    /// 常驻(默认):panic 即终止,向 watch 者发送 Terminated(Panicked),不重启。
101    #[default]
102    Permanent,
103    /// 瞬态:panic 后按指数退避用工厂重建 Actor,直至达到 `max_restarts`;
104    /// 超限后以 [`StopCause::ResourceLimit`] 终止。
105    ///
106    /// 退避序列:`backoff * 2^(restarts-1)`(位移封顶 2^10)。
107    /// `reset_after` 为恢复窗口:距上次失败超过该时长则重启计数清零。
108    Transient {
109        max_restarts: u32,
110        backoff: Duration,
111        reset_after: Duration,
112    },
113}
114
115/// spawn 选项。
116#[derive(Debug, Clone)]
117pub struct SpawnOptions {
118    pub(crate) name: Option<ActorName>,
119    pub(crate) restart: RestartPolicy,
120    pub(crate) parent: Option<ActorId>,
121}
122
123impl SpawnOptions {
124    /// 匿名 spawn。
125    pub fn void() -> Self {
126        Self {
127            name: None,
128            restart: RestartPolicy::default(),
129            parent: None,
130        }
131    }
132
133    /// 命名 spawn。
134    pub fn named(name: impl Into<ActorName>) -> Self {
135        Self {
136            name: Some(name.into()),
137            ..Self::void()
138        }
139    }
140
141    /// 设置名称。
142    pub fn with_name(mut self, name: impl Into<ActorName>) -> Self {
143        self.name = Some(name.into());
144        self
145    }
146
147    /// 设置监督策略。
148    pub fn with_restart(mut self, policy: RestartPolicy) -> Self {
149        self.restart = policy;
150        self
151    }
152
153    pub(crate) fn with_parent(mut self, parent: ActorId) -> Self {
154        self.parent = Some(parent);
155        self
156    }
157}
158
159impl Default for SpawnOptions {
160    fn default() -> Self {
161        Self::void()
162    }
163}
164
165impl From<&str> for SpawnOptions {
166    fn from(n: &str) -> Self {
167        Self::named(n)
168    }
169}
170
171impl From<String> for SpawnOptions {
172    fn from(n: String) -> Self {
173        Self::named(n)
174    }
175}
176
177impl From<ActorName> for SpawnOptions {
178    fn from(n: ActorName) -> Self {
179        Self::named(n)
180    }
181}
182
183/// 系统配置。
184#[derive(Debug, Clone)]
185pub struct ActorConfig {
186    /// 控制通道默认容量(Actor 策略声明 `capacity: 0` 时采用)。
187    pub mailbox_capacity: usize,
188    /// 专用信号通道容量(watch 终止通知等系统信号)。
189    pub signal_channel_capacity: usize,
190    /// [`shutdown`](ActorSystem::shutdown) 等待单个 Actor 退出的宽限期,
191    /// 超时后强制注销(记 warn 日志)。强制注销只移除注册表条目:
192    /// 该 Actor 变为不可寻址(`is_alive == false`),但其任务若阻塞在
193    /// `handle` 中是否继续运行由 [`abort_on_grace_timeout`] 决定。
194    ///
195    /// [`abort_on_grace_timeout`]: ActorConfig::abort_on_grace_timeout
196    pub shutdown_grace: Duration,
197    /// 宽限期超时后是否硬终止(abort)卡死的 Actor 事件循环任务。
198    ///
199    /// - `false`(默认):仅强制注销。被注销的任务若阻塞在 `handle`
200    ///   中仍会继续运行,外部持有的 `ActorRef` 仍可向其投递消息并被
201    ///   消费;需要硬终止保证时应约束 `handle` 不做无上界阻塞。
202    /// - `true`:注销之外再 [`abort`](tokio::task::AbortHandle::abort)
203    ///   事件循环任务 —— 任务在下一个 `await` 点被取消丢弃,Actor
204    ///   实例的 `Drop` 立即执行,**不再执行 `on_stop`**。适用于失控
205    ///   保护:宁可丢弃卡死的实例,也不让它继续持有链路/硬件资源。
206    ///
207    /// abort 只能在 await 点生效:既不 await 也不 yield 的同步死循环
208    /// (阻塞线程的 `handle`)无法被取消,任何开关下都需业务侧自律。
209    pub abort_on_grace_timeout: bool,
210}
211
212impl Default for ActorConfig {
213    fn default() -> Self {
214        Self {
215            mailbox_capacity: DEFAULT_MAILBOX_CAPACITY,
216            signal_channel_capacity: SIGNAL_CHANNEL_CAPACITY,
217            shutdown_grace: Duration::from_secs(2),
218            abort_on_grace_timeout: false,
219        }
220    }
221}
222
223/// 专用信号通道默认容量:信号流量极小(watch 终止通知、看门狗触发
224/// 标记 —— 每 Actor 至多一条在途标记),与用户消息邮箱物理隔离,
225/// 绝不排队在消息积压之后。
226///
227/// 可经 [`ActorConfig::signal_channel_capacity`] 调整;
228/// 投递端带背压重试,满通道不再丢弃 Terminated(见 `SignalSink`)。
229const SIGNAL_CHANNEL_CAPACITY: usize = 64;
230
231/// 类型擦除的信号投递端(冷路径,写入专用信号通道)。
232trait SignalSink: Send + Sync {
233    /// 非阻塞投递:常规路径 `try_send` 零任务开销;满时转交独立任务
234    /// 执行带背压的 `send`,保证信号**恰好一次**送达且 finalize 不被
235    /// 消费停滞的接收方卡死(如 watcher 在 handle 内部同步等待
236    /// 目标退出的场景)。仅当接收端已被丢弃时投递终止(无害)。
237    fn push_signal(&self, sig: Signal);
238}
239
240impl SignalSink for mpsc::Sender<Signal> {
241    fn push_signal(&self, sig: Signal) {
242        // 常规路径 try_send 零任务开销(Terminated 流量极小,容量 64 几乎
243        // 不满);满时才转交独立任务执行带背压的 send,保证 Terminated
244        // **恰好一次**送达且 finalize 不被消费停滞的接收方卡死(如 watcher
245        // 在 handle 内部同步等待目标退出的场景)。仅当接收端已被丢弃时
246        // 投递终止(无害)。
247        match self.try_send(sig) {
248            Ok(()) => {}
249            Err(mpsc::error::TrySendError::Full(sig)) => {
250                // 无异步上下文(runtime 已销毁 / 收尾路径的 Drop)时不做
251                // spawn:此时没有可送达的接收方,丢弃即终止语义
252                let Ok(handle) = tokio::runtime::Handle::try_current() else {
253                    tracing::warn!("信号通道满载且无异步上下文(系统收尾),Terminated 通知丢弃");
254                    return;
255                };
256                let tx = self.clone();
257                handle.spawn(async move {
258                    if tx.send(sig).await.is_err() {
259                        tracing::debug!("Terminated 投递中止:信号通道已关闭(目标已终止)")
260                    }
261                });
262            }
263            Err(mpsc::error::TrySendError::Closed(_)) => {
264                tracing::debug!("Terminated 投递中止:信号通道已关闭(目标已终止)")
265            }
266        }
267    }
268}
269
270/// 类型擦除的引用快照(供 [`ActorSystem::find`] 向下转型,冷路径一次性)。
271trait AnyRef: Send + Sync {
272    fn as_any(&self) -> &dyn std::any::Any;
273}
274
275impl<M: ActorMsg> AnyRef for ActorRef<M> {
276    fn as_any(&self) -> &dyn std::any::Any {
277        self
278    }
279}
280
281/// 注册表条目 —— 只保存控制面所需的最小擦除句柄。
282struct Entry {
283    id: ActorId,
284    name: Option<ActorName>,
285    /// 消息类型名(诊断日志用)。
286    kind: &'static str,
287    sig: Box<dyn SignalSink>,
288    /// 相位/停止通道:停止请求落 `Stopped`(见 [`request_stop`]),终态由
289    /// `FinalizeGuard` 收口 —— watch 保留末值,死后查询照常可读。
290    stop: Arc<watch::Sender<ActorPhase>>,
291    /// 最终退出信号:finalize 时置 true(stop_and_wait / shutdown 依赖它)。
292    exit: watch::Sender<bool>,
293    /// 当前世代事件循环任务的 abort 句柄(由 Supervisor 在 spawn 后写入;
294    /// 供 [`ActorSystem::force_deregister`] 在
295    /// [`ActorConfig::abort_on_grace_timeout`] 开启时硬终止卡死任务)。
296    abort: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>>,
297    typed: Box<dyn AnyRef>,
298}
299
300/// 系统内部共享状态。
301pub(crate) struct SystemInner {
302    registry: DashMap<ActorId, Entry>,
303    by_name: DashMap<ActorName, ActorId>,
304    /// target -> watchers(watch 关系索引:谁在监视我)。
305    watched_by: DashMap<ActorId, Vec<ActorId>>,
306    /// watcher -> targets(watch 关系索引:我在监视谁)。
307    /// 供 watcher 退出时统一清理登记,杜绝死 watcher 残留。
308    watching: DashMap<ActorId, Vec<ActorId>>,
309    next_id: AtomicU64,
310    /// 看门狗武装世代号分配器(全局单调,跨世代/跨实例不重复)。
311    next_arm: AtomicU64,
312    /// 未 shutdown 泄漏检测的用户句柄计数(见 [`ActorSystem::drop`])。
313    tracked_handles: AtomicUsize,
314    shutdown: AtomicBool,
315    shutdown_tx: watch::Sender<bool>,
316    pub(crate) timer: TimerDriver,
317    clock: ClockSource,
318    config: ActorConfig,
319}
320
321impl SystemInner {
322    /// 分配一个全局唯一的看门狗武装世代号(从 1 起递增)。
323    pub(crate) fn next_watchdog_arm(&self) -> u64 {
324        self.next_arm.fetch_add(1, AtomicOrdering::Relaxed)
325    }
326
327    /// 名称注册(spawn 路径唯一入口)。调用契约:`registry` 中必须已有 `id` 条目。
328    ///
329    /// 唯一性判定依赖插入顺序:存活 Actor 恒为 registry → by_name,
330    /// 最终退出([`FinalizeGuard`])恒为 registry 摘除 → by_name 摘除。
331    /// 因此"by_name 命中 cur 而 registry 无 cur"只剩目标已最终退出、
332    /// by_name 尚未摘除的陈旧条目一种解释,可安全顶替;并发同名 spawn 的
333    /// registry 条目必然先于其名称可见,不会被误判为陈旧。
334    ///
335    /// (回归用例见 `tests/test_named_registry.rs`。)
336    fn register_name(&self, name: &ActorName, id: ActorId) -> Result<(), ActorError> {
337        use dashmap::mapref::entry::Entry as NameEntry;
338        match self.by_name.entry(name.clone()) {
339            NameEntry::Vacant(v) => {
340                v.insert(id);
341                Ok(())
342            }
343            NameEntry::Occupied(occupied) => {
344                let cur = *occupied.get();
345                drop(occupied);
346                if self.registry.contains_key(&cur) {
347                    return Err(ActorError::DuplicateName(name.clone()));
348                }
349                // 陈旧条目:目标已最终退出(finalize 先注销 registry、
350                // 后摘除 by_name 的窄窗口)——顶替之,避免"观察到
351                // is_alive=false 后立刻重名 spawn"偶发 DuplicateName。
352                // 条件删除保证不误伤并发拿到该名称的新 spawn。
353                self.by_name.remove_if(name, |_, &cur_id| cur_id == cur);
354                match self.by_name.entry(name.clone()) {
355                    NameEntry::Vacant(v) => {
356                        v.insert(id);
357                        Ok(())
358                    }
359                    NameEntry::Occupied(_) => Err(ActorError::DuplicateName(name.clone())),
360                }
361            }
362        }
363    }
364
365    /// 登记 watch 关系。
366    ///
367    /// 幂等:重复登记同一 (watcher, target) 为 no-op —— 同一 watcher
368    /// 跨世代重新 watch 不得产生重复登记与重复通知。
369    /// 两个方向的索引各自去重、无条件维护,具备自愈性(任一侧缺失
370    /// 都可在下次登记时补齐)。
371    pub(crate) fn register_watch(&self, watcher: ActorId, target: ActorId) {
372        let mut list = self.watched_by.entry(target).or_default();
373        if !list.contains(&watcher) {
374            list.push(watcher);
375        }
376        drop(list);
377        let mut rev = self.watching.entry(watcher).or_default();
378        if !rev.contains(&target) {
379            rev.push(target);
380        }
381    }
382
383    /// 解除 watch 登记;返回 watcher 是否确实从目标列表中被移除
384    /// (供 [`watch_id`](crate::ActorContext::watch_id) 竞态复核区分
385    /// "登记仍存"与"已被 finalize 消费",保证 Terminated 恰好一次)。
386    pub(crate) fn unregister_watch(&self, watcher: ActorId, target: ActorId) -> bool {
387        let removed = match self.watched_by.get_mut(&target) {
388            Some(mut list) => {
389                let before = list.len();
390                list.retain(|&w| w != watcher);
391                let removed = list.len() != before;
392                let now_empty = list.is_empty();
393                drop(list);
394                if now_empty {
395                    // 仅在仍为空时删除条目:remove_if 持分片写锁原子判定,
396                    // 不误删并发 register_watch 在本间隙重建的 watcher 列表
397                    self.watched_by
398                        .remove_if(&target, |_, watchers| watchers.is_empty());
399                }
400                removed
401            }
402            None => false,
403        };
404        // 同步清理反向索引(watching[watcher]):与 watched_by 侧
405        // 是否命中无关(登记可能已被 finalize 摘取消费)
406        if let Some(mut rev) = self.watching.get_mut(&watcher) {
407            rev.retain(|&t| t != target);
408            let now_empty = rev.is_empty();
409            drop(rev);
410            if now_empty {
411                self.watching
412                    .remove_if(&watcher, |_, targets| targets.is_empty());
413            }
414        }
415        removed
416    }
417
418    /// watcher 退出清理:移除其作为"监视方"的全部登记
419    /// (另一方向 —— 作为 target 的被监视登记 —— 由 finalize 摘取通知)。
420    pub(crate) fn cleanup_watcher(&self, watcher: ActorId) {
421        if let Some((_, targets)) = self.watching.remove(&watcher) {
422            for target in targets {
423                if let Some(mut list) = self.watched_by.get_mut(&target) {
424                    list.retain(|&w| w != watcher);
425                    let now_empty = list.is_empty();
426                    drop(list);
427                    if now_empty {
428                        self.watched_by
429                            .remove_if(&target, |_, watchers| watchers.is_empty());
430                    }
431                }
432            }
433        }
434    }
435
436    fn push_signal(&self, id: ActorId, sig: ActorSignal) {
437        if let Some(e) = self.registry.get(&id) {
438            e.sig.push_signal(Signal::System(sig));
439        }
440    }
441}
442
443/// spawn 中途失败/panic 的注册回滚守卫(与 [`FinalizeGuard`] 同属清理守卫)。
444///
445/// 覆盖 `registry.insert` 之后到 `tokio::spawn` 成功返回之间的全部中途退出
446/// 路径:重名拒绝(`register_name` 返回 `Err`)、父监视登记之后的任何 panic、
447/// `tokio::spawn` 在无 runtime 上下文 / 运行期已关闭时 panic(它不返回
448/// `Err`)等。没有它,这些路径会留下幽灵条目(`is_alive` 恒 true、`find`
449/// 返回事件循环从未启动的引用)与名称占用。
450///
451/// 回滚只做条目/名称/父监视登记的反向清理:该 id 从未对外发布(`ActorRef`
452/// 仅在 spawn 成功时交给调用方),不存在需要通知的 watcher。
453struct SpawnRollback {
454    inner: Arc<SystemInner>,
455    id: ActorId,
456    name: Option<ActorName>,
457    parent: Option<ActorId>,
458    armed: bool,
459}
460
461impl SpawnRollback {
462    fn disarm(&mut self) {
463        self.armed = false;
464    }
465}
466
467impl Drop for SpawnRollback {
468    fn drop(&mut self) {
469        if !self.armed {
470            return;
471        }
472        self.inner.registry.remove(&self.id);
473        if let Some(n) = &self.name {
474            self.inner.by_name.remove_if(n, |_, &cur| cur == self.id);
475        }
476        if let Some(parent) = self.parent {
477            self.inner.unregister_watch(parent, self.id);
478        }
479        // 重名拒绝是常规结果、panic 中途退出是异常路径,统一走 debug:
480        // 两种情况都只需保证注册表/名称干净
481        tracing::debug!(actor = %self.id, "spawn 未完成,已回滚注册表与名称登记");
482    }
483}
484
485/// Actor 运行时容器(廉价 Clone,内部 Arc 共享)。
486///
487/// 持有克隆**不会**自动延长 Actor 的生命周期,也不会阻止其被停止;
488/// 但丢弃全部克隆前**必须**调用 [`shutdown`](ActorSystem::shutdown):
489/// 监督者恒持邮箱发送端,直接丢弃系统不会让任何 Actor 任务退出
490/// (它们将随 tokio 运行时存活至进程结束)。用户句柄(`new` /
491/// `with_config` 及其 Clone)在未 shutdown 时被**全部**丢弃且仍有
492/// Actor 注册,会记录 warn 日志(见 `Drop` 实现)。
493pub struct ActorSystem {
494    pub(crate) inner: Arc<SystemInner>,
495    /// 是否为用户句柄。仅用户句柄参与"最后一个句柄"泄漏检测;内部
496    /// 持有者(监督者/最终退出守卫)与派生访问器([`ActorRef::system`])
497    /// 使用 [`internal`](ActorSystem::internal) 构造的未跟踪句柄 ——
498    /// 否则内部强引用恒使计数不为零,泄漏警告永不触发。
499    tracked: bool,
500}
501
502impl Clone for ActorSystem {
503    fn clone(&self) -> Self {
504        if self.tracked {
505            self.inner
506                .tracked_handles
507                .fetch_add(1, AtomicOrdering::Relaxed);
508        }
509        Self {
510            inner: self.inner.clone(),
511            tracked: self.tracked,
512        }
513    }
514}
515
516impl Drop for ActorSystem {
517    fn drop(&mut self) {
518        if !self.tracked || self.inner.tracked_handles.fetch_sub(1, AtomicOrdering::AcqRel) != 1 {
519            return; // 未跟踪的派生句柄,或仍有其他用户句柄存活
520        }
521        let alive = self.inner.registry.len();
522        if alive > 0 && !self.inner.shutdown.load(AtomicOrdering::Acquire) {
523            tracing::warn!(
524                actor_count = alive,
525                "ActorSystem 的最后一个句柄在未调用 shutdown 的情况下被丢弃:\
526                 {alive} 个 Actor 任务将继续运行(监督者恒持邮箱发送端)\
527                 直至 tokio 运行时销毁,请改调 ActorSystem::shutdown"
528            );
529        }
530    }
531}
532
533impl ActorSystem {
534    /// 以默认配置创建系统(tokio 实时钟,`sleep_until` 零装箱)。
535    ///
536    /// # Panics
537    ///
538    /// 必须在 tokio runtime 上下文内调用(定时器驱动任务经
539    /// `tokio::spawn` 启动);在无 runtime 的同步上下文中调用将 panic。
540    pub fn new() -> Self {
541        Self::with_config(ActorConfig::default())
542    }
543
544    /// 以指定配置创建系统。
545    ///
546    /// # Panics
547    ///
548    /// 同 [`new`](Self::new):必须在 tokio runtime 上下文内调用。
549    pub fn with_config(config: ActorConfig) -> Self {
550        Self::with_clock_source(config, ClockSource::Tokio)
551    }
552
553    /// 注入自定义时钟(测试可虚拟时间,配合 [`Clock`] 抽象)。
554    ///
555    /// # Panics
556    ///
557    /// 同 [`new`](Self::new):必须在 tokio runtime 上下文内调用。
558    pub fn with_clock(config: ActorConfig, clock: Arc<dyn Clock>) -> Self {
559        Self::with_clock_source(config, ClockSource::Custom(clock))
560    }
561
562    fn with_clock_source(config: ActorConfig, clock: ClockSource) -> Self {
563        let timer = TimerDriver::spawn(clock.clone());
564        let (shutdown_tx, _) = watch::channel(false);
565        Self {
566            inner: Arc::new(SystemInner {
567                registry: DashMap::new(),
568                by_name: DashMap::new(),
569                watched_by: DashMap::new(),
570                watching: DashMap::new(),
571                next_id: AtomicU64::new(1),
572                next_arm: AtomicU64::new(1),
573                tracked_handles: AtomicUsize::new(1),
574                shutdown: AtomicBool::new(false),
575                shutdown_tx,
576                timer,
577                clock,
578                config,
579            }),
580            tracked: true,
581        }
582    }
583
584    /// 内部持有者/派生访问器用的未跟踪句柄(不参与未 shutdown 泄漏检测)。
585    pub(crate) fn from_inner(inner: Arc<SystemInner>) -> Self {
586        Self {
587            inner,
588            tracked: false,
589        }
590    }
591
592    fn internal(&self) -> Self {
593        Self::from_inner(self.inner.clone())
594    }
595
596    /// 系统配置。
597    pub fn config(&self) -> &ActorConfig {
598        &self.inner.config
599    }
600
601    /// 当前时间(统一走系统时钟源,测试下即虚拟时间)。
602    pub fn now(&self) -> tokio::time::Instant {
603        self.inner.clock.now()
604    }
605
606    /// 是否已关闭。
607    pub fn is_shutdown(&self) -> bool {
608        self.inner.shutdown.load(AtomicOrdering::Acquire)
609    }
610
611    // -----------------------------------------------------------------------
612    // spawn
613    // -----------------------------------------------------------------------
614
615    /// 创建并启动一个 Actor,返回类型化引用。
616    ///
617    /// `opts` 可为 [`SpawnOptions`],也可为 `&str` / [`ActorName`](命名快捷)。
618    ///
619    /// # 错误
620    /// - [`ActorError::DuplicateName`] 名称已被占用;
621    /// - [`ActorError::SystemShutdown`] 系统已关闭。
622    ///
623    /// # Panics
624    ///
625    /// 必须在 tokio runtime 上下文内调用(Actor 事件循环经 `tokio::spawn`
626    /// 启动):无 runtime 或运行期已关闭时 panic;此时注册表条目与名称由
627    /// 回滚守卫清理,不留幽灵条目。
628    pub fn spawn<A>(
629        &self,
630        opts: impl Into<SpawnOptions>,
631        actor: A,
632    ) -> Result<ActorRef<A::Message>, ActorError>
633    where
634        A: Actor,
635    {
636        self.spawn_inner(opts.into(), ActorSource::Once(Some(actor)))
637    }
638
639    /// 匿名 spawn(自动分配 ID)。
640    ///
641    /// # Panics
642    ///
643    /// 同 [`spawn`](Self::spawn):必须在 tokio runtime 上下文内调用。
644    pub fn spawn_anonymous<A>(&self, actor: A) -> Result<ActorRef<A::Message>, ActorError>
645    where
646        A: Actor,
647    {
648        self.spawn(SpawnOptions::void(), actor)
649    }
650
651    /// 命名 spawn。重名返回 [`ActorError::DuplicateName`]。
652    ///
653    /// # Panics
654    ///
655    /// 同 [`spawn`](Self::spawn):必须在 tokio runtime 上下文内调用。
656    pub fn spawn_named<A>(
657        &self,
658        name: impl Into<ActorName>,
659        actor: A,
660    ) -> Result<ActorRef<A::Message>, ActorError>
661    where
662        A: Actor,
663    {
664        self.spawn(SpawnOptions::named(name), actor)
665    }
666
667    /// 受监督的工厂 spawn:panic 后按策略用 `factory` 重建实例。
668    ///
669    /// 重启期间**已入队未取**的邮箱消息不丢失(信箱跨世代续存),恢复后
670    /// 新世代继续消费;panic 时正在 `handle` 中的那条已随世代消费,不重放。
671    /// 每个世代的 `on_start` 重新执行。
672    ///
673    /// # Panics
674    ///
675    /// 同 [`spawn`](Self::spawn):必须在 tokio runtime 上下文内调用。
676    /// 工厂在 spawn 期间不会被执行(首个实例在监督任务内构造),其 panic
677    /// 由 `catch_unwind` 捕获并按监督策略处置。
678    pub fn spawn_supervised<A, F>(
679        &self,
680        opts: impl Into<SpawnOptions>,
681        factory: F,
682    ) -> Result<ActorRef<A::Message>, ActorError>
683    where
684        A: Actor,
685        F: Fn() -> A + Send + Sync + 'static,
686    {
687        self.spawn_inner(opts.into(), ActorSource::Factory(Arc::new(factory)))
688    }
689
690    fn spawn_inner<A>(
691        &self,
692        opts: SpawnOptions,
693        source: ActorSource<A>,
694    ) -> Result<ActorRef<A::Message>, ActorError>
695    where
696        A: Actor,
697    {
698        let inner = self.inner.clone();
699        if self.is_shutdown() {
700            return Err(ActorError::SystemShutdown);
701        }
702        // Once 源 + Transient 策略:panic 后无法重建,提前给出诊断
703        if matches!(source, ActorSource::Once(_))
704            && matches!(opts.restart, RestartPolicy::Transient { .. })
705        {
706            tracing::warn!(
707                "spawn 使用一次性实例但声明了 Transient 策略;panic 后将无法重启(请改用 spawn_supervised)"
708            );
709        }
710        let id = ActorId::new(inner.next_id.fetch_add(1, AtomicOrdering::Relaxed));
711        let name = opts.name.clone();
712
713        let policy = A::mailbox_policy().resolve(inner.config.mailbox_capacity);
714        let (ctl_tx, ctl_rx) = mpsc::channel::<A::Message>(policy.capacity());
715        let (sig_tx, sig_rx) = mpsc::channel::<Signal>(inner.config.signal_channel_capacity.max(1));
716        let (stop_tx, stop_rx) = watch::channel(ActorPhase::Running);
717        let stop_tx = Arc::new(stop_tx);
718        let (slot_tx, slot_rx) = if policy.has_data_port() {
719            let (w, r) = latest_slot::<A::Message>();
720            (Some(w), Some(r))
721        } else {
722            (None, None)
723        };
724        let (exit_tx, _) = watch::channel(false);
725        // 世代任务的 abort 句柄槽:创建时为空,Supervisor 每世代 spawn 后
726        // 写入;force_deregister 在宽限超时且配置开启时取用
727        let abort_slot: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>> =
728            Arc::new(std::sync::Mutex::new(None));
729
730        let aref = new_ref(
731            id,
732            name.clone(),
733            ctl_tx.clone(),
734            stop_tx.clone(),
735            slot_tx,
736            inner.clock.clone(),
737            Arc::downgrade(&inner),
738        );
739        tracing::debug!(actor = %id, kind = std::any::type_name::<A::Message>(), capacity = policy.capacity(), "Actor 已注册");
740        // 注册顺序契约:先 registry、后 by_name(与 finalize 相反)。
741        // 存活条目的 registry 条目恒先于名称可见,register_name 才能把
742        // "by_name 有而 registry 无"唯一地解释为最终退出的陈旧条目,
743        // 否则并发同名 spawn 会互判对方为陈旧而双双成功。
744        inner.registry.insert(
745            id,
746            Entry {
747                id,
748                name: name.clone(),
749                kind: std::any::type_name::<A::Message>(),
750                sig: Box::new(sig_tx.clone()),
751                stop: stop_tx.clone(),
752                exit: exit_tx.clone(),
753                abort: abort_slot.clone(),
754                typed: Box::new(aref.clone()),
755            },
756        );
757        // 回滚守卫:重名拒绝、父监视登记之后的任何 panic、tokio::spawn
758        // 因无 runtime 上下文 / 运行期已关闭而 panic 都不得留下幽灵条目
759        let mut rollback = SpawnRollback {
760            inner: inner.clone(),
761            id,
762            name: name.clone(),
763            parent: opts.parent,
764            armed: true,
765        };
766        if let Some(n) = &name {
767            inner.register_name(n, id)?;
768        }
769        if let Some(parent) = opts.parent {
770            inner.register_watch(parent, id);
771        }
772
773        // 最终退出守卫先于 Supervisor 构造:finalize 需要停止通道发送端
774        // 写终态相位(stop_tx 本体随后移入 Supervisor,此处克隆一份)
775        let guard = FinalizeGuard {
776            system: self.internal(),
777            id,
778            name: name.clone(),
779            exit_tx,
780            stop_tx: stop_tx.clone(),
781            done: false,
782        };
783        let supervisor = Supervisor {
784            system: self.internal(),
785            id,
786            name: name.clone(),
787            source,
788            policy: opts.restart,
789            ctl_tx,
790            stop_tx,
791            stop_rx,
792            slot_rx,
793            generation: 0, // 首个世代在 run 中 +1 → generation = 1
794            restarts: 0,
795            mailbox: Arc::new(tokio::sync::Mutex::new(ctl_rx)),
796            sigbox: Arc::new(tokio::sync::Mutex::new(sig_rx)),
797            sig_tx: sig_tx.clone(),
798            abort: abort_slot,
799            guard,
800            shutdown_rx: inner.shutdown_tx.subscribe(),
801        };
802        tokio::spawn(async move { supervisor.run().await });
803        rollback.disarm();
804        Ok(aref)
805    }
806
807    // -----------------------------------------------------------------------
808    // 查询与寻址
809    // -----------------------------------------------------------------------
810
811    /// 按名称查找类型化引用;不存在或消息类型不匹配返回 None。
812    ///
813    /// 以 `&str` 直查([`ActorName: Borrow<str>`](std::borrow::Borrow)),
814    /// 查询路径零分配。
815    pub fn find<M: ActorMsg>(&self, name: impl AsRef<str>) -> Option<ActorRef<M>> {
816        let id = *self.inner.by_name.get(name.as_ref())?;
817        self.find_by_id::<M>(id)
818    }
819
820    /// 按 ID 查找类型化引用(消息类型不匹配返回 None)。
821    pub fn find_by_id<M: ActorMsg>(&self, id: ActorId) -> Option<ActorRef<M>> {
822        self.inner.registry.get(&id).and_then(|e| {
823            e.typed
824                .as_any()
825                .downcast_ref::<ActorRef<M>>()
826                .cloned()
827        })
828    }
829
830    /// 名称 → ID 解析(`&str` 直查,零分配)。
831    pub fn resolve_name(&self, name: impl AsRef<str>) -> Option<ActorId> {
832        self.inner.by_name.get(name.as_ref()).map(|r| *r)
833    }
834
835    /// Actor 是否仍注册在系统内(终止中/已终止返回 false)。
836    pub fn is_alive(&self, id: ActorId) -> bool {
837        self.inner.registry.contains_key(&id)
838    }
839
840    /// 当前注册 Actor 数量。
841    pub fn actor_count(&self) -> usize {
842        self.inner.registry.len()
843    }
844
845    /// 全部活跃 Actor 的 ID。
846    pub fn actor_ids(&self) -> Vec<ActorId> {
847        self.inner.registry.iter().map(|e| *e.key()).collect()
848    }
849
850    // -----------------------------------------------------------------------
851    // 停止与关闭
852    // -----------------------------------------------------------------------
853
854    /// 请求停止指定 Actor(控制面信号,邮箱满也能送达)。
855    ///
856    /// 非阻塞;返回是否找到存活条目并完成通知(`false` 表示 Actor
857    /// 不存在或已最终退出 —— 监督者不再持停止通道接收端)。
858    /// 请求落值后该 Actor 相位即为
859    /// [`Stopped { cause: Requested }`](crate::ActorPhase::Stopped)。
860    #[must_use = "返回是否成功送达停止请求(false 表示 Actor 不存在)"]
861    pub fn stop(&self, id: ActorId) -> bool {
862        match self.inner.registry.get(&id) {
863            Some(e) => request_stop(&e.stop, StopCause::Requested),
864            None => false,
865        }
866    }
867
868    /// 按名称请求停止。
869    #[must_use = "按名称停止的结果可能被静默忽略(false 表示未找到)"]
870    pub fn stop_named(&self, name: impl AsRef<str>) -> bool {
871        match self.resolve_name(name) {
872            Some(id) => self.stop(id),
873            None => false,
874        }
875    }
876
877    /// 请求停止并等待其最终退出(真正 await)。
878    ///
879    /// 返回 `false` 表示条目已不存在(Actor 早已退出,无可等待);
880    /// `true` 表示观察到最终退出信号(含退出信号发送端随条目释放)。
881    ///
882    /// 无限期等待:Actor 卡死在长 `handle` / `on_stop` 中时本调用将
883    /// 永久挂起;需要上限请用
884    /// [`stop_and_wait_timeout`](ActorSystem::stop_and_wait_timeout)。
885    ///
886    /// # Panics
887    ///
888    /// 在目标 Actor 自身的 `handle` 内对自己调用会**立即 panic**(自调用
889    /// 防护):本调用阻塞等待该 Actor 的事件循环推进退出,而事件循环正
890    /// 阻塞在本调用上,必然死锁。Actor 请求自身停止请用 [`ActorContext::stop`]
891    /// 加返回 [`ActorAction::Stop`]。经 `tokio::spawn` 转手的调用不被识别为
892    /// 自调用(子任务无世代身份),仍会死锁。
893    pub async fn stop_and_wait(&self, id: ActorId) -> bool {
894        assert_not_self_call(id, "stop_and_wait");
895        let rx = self.inner.registry.get(&id).map(|e| e.exit.subscribe());
896        let _ = self.stop(id);
897        match rx {
898            Some(mut rx) => {
899                // finalize 时 send(true) 或 sender drop 都会结束 await
900                let _ = rx.changed().await;
901                true
902            }
903            None => false,
904        }
905    }
906
907    /// 请求停止并限时等待退出。
908    ///
909    /// 语义同 [`stop_and_wait`](ActorSystem::stop_and_wait),但超过
910    /// `timeout` 未观察到最终退出信号时返回
911    /// [`ActorError::Timeout`](停止请求本身已送达,Actor 可能仍在
912    /// 处理收尾逻辑)。等待走系统注入时钟,虚拟时间测试可确定推进。
913    ///
914    /// # Panics
915    ///
916    /// 自调用防护同 [`stop_and_wait`](ActorSystem::stop_and_wait):在目标
917    /// Actor 自身 `handle` 内对自己调用立即 panic(这里只会白等满
918    /// `timeout` 后返回 [`ActorError::Timeout`],属必然失败的调用)。
919    pub async fn stop_and_wait_timeout(
920        &self,
921        id: ActorId,
922        timeout: Duration,
923    ) -> Result<bool, ActorError> {
924        assert_not_self_call(id, "stop_and_wait_timeout");
925        let rx = self.inner.registry.get(&id).map(|e| e.exit.subscribe());
926        let _ = self.stop(id);
927        let Some(mut rx) = rx else {
928            return Ok(false);
929        };
930        let deadline = deadline_after(self.inner.clock.now(), timeout);
931        tokio::select! {
932            _ = rx.changed() => Ok(true),
933            _ = self.inner.clock.sleep_until(deadline) => Err(ActorError::Timeout(id)),
934        }
935    }
936
937    /// 优雅关闭整个系统:通知全部 Actor 停止并等待退出。
938    ///
939    /// 幂等。并发调用时仅首个调用者执行关闭流程,其余调用者立即
940    /// 返回 —— 可能先于全部 Actor 真正退出;需要确定性等待请串行
941    /// 调用或等待首个调用完成。关闭后
942    /// [`spawn`](ActorSystem::spawn) 被拒绝(返回
943    /// [`ActorError::SystemShutdown`])。超过
944    /// [`ActorConfig::shutdown_grace`] 仍未退出的 Actor 将被强制注销;
945    /// 是否进一步硬终止(abort)卡死的任务由
946    /// [`ActorConfig::abort_on_grace_timeout`] 决定(默认仅注销)。
947    ///
948    /// 终止通知语义:因本关闭请求退出的 Actor,watcher 收到的
949    /// [`Terminated`] 原因为 [`StopCause::SystemShutdown`](与显式
950    /// `stop` 的 [`StopCause::Requested`] 区分)。
951    ///
952    /// # 在 Actor 内部调用(自调用)
953    ///
954    /// 允许,且不会白等宽限期:调用者自身(世代任务)被识别并排除出
955    /// 等待集 —— 它的循环正阻塞在本调用上,纳入等待只会等满
956    /// `shutdown_grace` 后被误判超时强制注销。停止请求仍照常送达调用者,
957    /// 本调用返回后其 `handle` 正常返回,下一轮循环顶部见到停止位即
958    /// 优雅退出(`on_stop` 照常执行)。
959    ///
960    /// 经 `tokio::spawn` 转手的调用(在派生任务中关系统)**不**被识别为
961    /// 自调用(标记不跨任务继承),将退化为等待其所属 Actor 直到宽限
962    /// 超时;这种接线请改为 Actor 内 [`ActorContext::stop`] /
963    /// [`ActorAction::Stop`],由外部任务负责关闭系统。
964    pub async fn shutdown(&self) {
965        if self
966            .inner
967            .shutdown
968            .compare_exchange(
969                false,
970                true,
971                AtomicOrdering::AcqRel,
972                AtomicOrdering::Acquire,
973            )
974            .is_err()
975        {
976            return; // 幂等:已有关闭流程执行过/进行中
977        }
978        tracing::info!(actor_count = self.actor_count(), "ActorSystem 开始优雅关闭");
979        let _ = self.inner.shutdown_tx.send(true);
980        // 自调用识别:调用方若为某 Actor 的世代任务,其事件循环正阻塞在
981        // 本调用上、无法推进退出,须排除出等待集(停止请求仍送达)
982        let caller = GENERATION_ACTOR.try_with(|id| *id).ok();
983
984        // 快照:全部条目的停止端与退出监视端
985        let pending: Vec<(ActorId, Option<ActorName>, watch::Receiver<bool>)> = self
986            .inner
987            .registry
988            .iter()
989            .map(|e| (e.id, e.name.clone(), e.exit.subscribe()))
990            .collect();
991        for (id, _, _) in &pending {
992            if let Some(e) = self.inner.registry.get(id) {
993                // 相位直接落 SystemShutdown(而非占位 Requested):关闭期
994                // 查询即读到准确原因;卡死被强注销的 Actor 亦然(其
995                // finalize 永不执行,相位由这次写入兜底)
996                let _ = request_stop(&e.stop, StopCause::SystemShutdown);
997            }
998        }
999
1000        // 并发等待全部 Actor 退出:单个宽限期内并行等待,
1001        // 总耗时 ≤ grace。
1002        // 宽限计时走系统时钟(与定时器/ask 同源,虚拟时间测试可推进)
1003        let grace = self.inner.config.shutdown_grace;
1004        let clock = self.inner.clock.clone();
1005        let mut waits = tokio::task::JoinSet::new();
1006        for (id, name, rx) in pending {
1007            if Some(id) == caller {
1008                tracing::debug!(actor = %id, "shutdown 由该 Actor 自身发起,跳过其退出等待");
1009                continue;
1010            }
1011            let clock = clock.clone();
1012            waits.spawn(async move {
1013                let mut rx = rx;
1014                let deadline = deadline_after(clock.now(), grace);
1015                let timed_out = tokio::select! {
1016                    _ = rx.changed() => false,
1017                    _ = clock.sleep_until(deadline) => true,
1018                };
1019                (id, name, timed_out)
1020            });
1021        }
1022        while let Some(joined) = waits.join_next().await {
1023            match joined {
1024                Ok((id, name, timed_out)) => {
1025                    if timed_out {
1026                        tracing::warn!(%id, ?name, "Actor 未在宽限期内退出,强制注销");
1027                        self.force_deregister(id, name.as_ref());
1028                    }
1029                }
1030                Err(e) => tracing::warn!("关闭等待任务异常:{e}"),
1031            }
1032        }
1033        tracing::info!("ActorSystem 已完全关闭");
1034    }
1035
1036    /// 强制注销(仅 shutdown 宽限期超时路径触发)。
1037    ///
1038    /// 注销与通知之外,当 [`ActorConfig::abort_on_grace_timeout`] 开启时
1039    /// 硬终止该 Actor 的事件循环任务 —— abort 句柄经注册表条目与
1040    /// Supervisor 共享,事件循环任务可被外部取消:任务
1041    /// 在下一个 `await` 点被取消,实例 `Drop` 立即执行(不执行 `on_stop`)。
1042    /// 开关关闭(默认)时只注销:被注销的 Actor 变为不可寻址,但任务本身
1043    /// 继续存活直至其 `handle`/`on_stop` 自行完成。
1044    ///
1045    /// 尽力而为:世代任务 `tokio::spawn` 返回与句柄发布之间存在极窄窗口
1046    /// (无 await 点,仅线程抢占可观测),窗口内超时取不到句柄、错过
1047    /// abort,任务按开关关闭的语义继续运行。
1048    fn force_deregister(&self, id: ActorId, name: Option<&ActorName>) {
1049        if let Some((_, entry)) = self.inner.registry.remove(&id) {
1050            if self.inner.config.abort_on_grace_timeout {
1051                let handle = entry.abort.lock().unwrap_or_else(|e| e.into_inner()).take();
1052                if let Some(h) = handle {
1053                    h.abort();
1054                    tracing::warn!(
1055                        actor = %id,
1056                        kind = entry.kind,
1057                        "宽限超时:已硬终止卡死的事件循环任务(实例 Drop 立即执行,on_stop 已跳过)"
1058                    );
1059                }
1060            }
1061            tracing::debug!(actor = %id, kind = entry.kind, "强制注销已捕获条目");
1062            drop(entry); // 释放 ctl/stop/exit,唤醒仍在 await 的引用方
1063        }
1064        if let Some(n) = name {
1065            self.inner.by_name.remove_if(n, |_, &cur| cur == id);
1066        }
1067        // 强杀(宽限期超时)同样必须完成两向 watch 登记清理与终止通知:
1068        // 通知若在此丢失,watchers 将永久等待。本路径仅由 shutdown 触发,
1069        // 终止原因记为系统关闭
1070        self.inner.cleanup_watcher(id);
1071        let terminated = Terminated {
1072            actor: id,
1073            name: name.cloned(),
1074            cause: StopCause::SystemShutdown,
1075            detail: None,
1076        };
1077        if let Some((_, watchers)) = self.inner.watched_by.remove(&id) {
1078            for w in watchers {
1079                self.inner
1080                    .push_signal(w, ActorSignal::Terminated(terminated.clone()));
1081            }
1082        }
1083    }
1084}
1085
1086impl Default for ActorSystem {
1087    fn default() -> Self {
1088        Self::new()
1089    }
1090}
1091
1092// ---------------------------------------------------------------------------
1093// Actor 实例来源
1094// ---------------------------------------------------------------------------
1095
1096enum ActorSource<A: Actor> {
1097    /// 一次性实例:panic 后无法重建。
1098    Once(Option<A>),
1099    /// 工厂:Transient 策略下按退避重建。
1100    Factory(Arc<dyn Fn() -> A + Send + Sync>),
1101}
1102
1103impl<A: Actor> ActorSource<A> {
1104    fn take(&mut self) -> Option<A> {
1105        match self {
1106            ActorSource::Once(slot) => slot.take(),
1107            ActorSource::Factory(f) => Some(f()),
1108        }
1109    }
1110
1111    fn is_renewable(&self) -> bool {
1112        match self {
1113            ActorSource::Once(slot) => slot.is_some(),
1114            ActorSource::Factory(_) => true,
1115        }
1116    }
1117}
1118
1119/// 世代实例获取结果([`Supervisor::take_actor`])。
1120enum SourceTaken<A: Actor> {
1121    /// 取得新实例。
1122    Ready(A),
1123    /// 一次性实例已耗尽(防御性分支,见 `Supervisor::run` 内注释)。
1124    Exhausted,
1125    /// 工厂(用户代码)panic,载荷文本经 `catch_unwind` 提取。
1126    FactoryPanicked(Option<String>),
1127}
1128
1129// ---------------------------------------------------------------------------
1130// 世代结果
1131// ---------------------------------------------------------------------------
1132
1133struct GenDone {
1134    cause: StopCause,
1135}
1136
1137enum GenOutcome {
1138    /// 事件循环正常退出。
1139    Exited(GenDone),
1140    /// 事件循环 panic;携带从 `JoinError` 载荷提取的文本详情。
1141    Panicked { detail: Option<String> },
1142}
1143
1144/// 从 panic 载荷提取可展示文本:`&'static str` / `String` 原样取出,
1145/// 其余类型载荷给兜底文本(载荷类型不可静态得知,仅提示非文本)。
1146fn payload_text(payload: Box<dyn std::any::Any + Send>) -> Option<String> {
1147    if let Some(s) = payload.downcast_ref::<&'static str>() {
1148        Some((*s).to_string())
1149    } else if let Some(s) = payload.downcast_ref::<String>() {
1150        Some(s.clone())
1151    } else {
1152        Some("panicked(非文本 panic 载荷)".to_string())
1153    }
1154}
1155
1156/// 从 `JoinError`(世代任务 panic)提取载荷文本。
1157fn panic_detail(je: tokio::task::JoinError) -> Option<String> {
1158    payload_text(je.into_panic())
1159}
1160
1161// ---------------------------------------------------------------------------
1162// 监督者
1163// ---------------------------------------------------------------------------
1164
1165struct Supervisor<A: Actor> {
1166    system: ActorSystem,
1167    id: ActorId,
1168    name: Option<ActorName>,
1169    source: ActorSource<A>,
1170    policy: RestartPolicy,
1171    ctl_tx: mpsc::Sender<A::Message>,
1172    stop_tx: Arc<watch::Sender<ActorPhase>>,
1173    stop_rx: watch::Receiver<ActorPhase>,
1174    slot_rx: Option<SlotReader<A::Message>>,
1175    /// 当前世代号(首个世代为 1,每次监督重启 +1)。
1176    generation: u32,
1177    /// 连续监督重启计数(reset_after 恢复窗口内清零)。
1178    restarts: u32,
1179    /// 邮箱租约:`Arc<Mutex>` 仅在世代交接时加锁一次(非每消息开销),
1180    /// panic 时接收端随互斥体存活,供新世代恢复消费。
1181    mailbox: Arc<tokio::sync::Mutex<mpsc::Receiver<A::Message>>>,
1182    /// 专用信号通道接收端(跨世代租约:重启期间信号不丢失)。
1183    sigbox: Arc<tokio::sync::Mutex<mpsc::Receiver<Signal>>>,
1184    /// 信号通道发送端(注入 [`ActorContext`],供 watch 竞态复核自投递
1185    /// 与看门狗触发标记回投)。
1186    sig_tx: mpsc::Sender<Signal>,
1187    /// 当前世代任务的 abort 句柄槽(与注册表条目共享):
1188    /// [`force_deregister`](ActorSystem::force_deregister) 在宽限超时且
1189    /// [`abort_on_grace_timeout`](ActorConfig::abort_on_grace_timeout)
1190    /// 开启时借此硬终止卡死的事件循环。
1191    abort: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>>,
1192    /// 最终退出守卫:注册表/索引清理、终止通知与 exit 信号由它收口,
1193    /// 任务异常展开路径由 `Drop` 兜底(见 [`FinalizeGuard`])。
1194    guard: FinalizeGuard,
1195    shutdown_rx: watch::Receiver<bool>,
1196}
1197
1198impl<A: Actor> Supervisor<A> {
1199    async fn run(mut self) {
1200        let mut last_failure: Option<tokio::time::Instant> = None;
1201        let last_cause;
1202        // 最近一次 panic 的文本详情:随 Panicked 臂更新,在
1203        // Panicked / ResourceLimit 终止时随 Terminated 下发;
1204        // 非 panic 派生的退出路径显式清空,避免陈旧详情混入
1205        let mut last_detail: Option<String> = None;
1206
1207        loop {
1208            if self.is_shutdown() {
1209                // 关闭窗口内注册的 Actor(spawn 检查与 shutdown 快照之间
1210                // 的 TOCTOU 间隙):生命周期钩子从未执行,需运维可见
1211                if self.generation == 0 {
1212                    tracing::warn!(
1213                        actor = %self.id,
1214                        name = ?self.name,
1215                        "Actor 在系统关闭流程中注册,未执行 on_start/on_stop 即退出"
1216                    );
1217                }
1218                last_cause = StopCause::SystemShutdown;
1219                last_detail = None;
1220                break;
1221            }
1222            if matches!(
1223                &*self.stop_rx.borrow_and_update(),
1224                ActorPhase::Stopped { .. }
1225            ) {
1226                last_cause = StopCause::Requested;
1227                last_detail = None;
1228                break;
1229            }
1230            let outcome = match self.take_actor() {
1231                SourceTaken::Ready(actor) => {
1232                    self.generation += 1;
1233                    self.run_one_generation(actor).await
1234                }
1235                SourceTaken::Exhausted => {
1236                    // 一次性实例已消耗。防御性分支:理论上不可达 ——
1237                    // Once+Permanent 在首次 panic 即终止,Once+Transient
1238                    // 在首次 panic 即 ResourceLimit,均不会带空源回到
1239                    // 循环顶部
1240                    last_cause = if self.restarts > 0 {
1241                        StopCause::ResourceLimit
1242                    } else {
1243                        StopCause::Panicked
1244                    };
1245                    break;
1246                }
1247                // 工厂(用户代码)panic:与世代 panic 走同一监督处置
1248                // (退避重试/超限终止),supervisor 任务本身不炸毁 ——
1249                // 否则注册表条目与名称将永久泄漏
1250                SourceTaken::FactoryPanicked(detail) => GenOutcome::Panicked { detail },
1251            };
1252            match outcome {
1253                GenOutcome::Exited(done) => {
1254                    // 系统关闭期由关闭请求终止的 Actor 对外报 SystemShutdown,
1255                    // 与显式 stop 的 Requested 区分(宽限强注销路径已在
1256                    // force_deregister 记同一原因,两条路径语义对齐)
1257                    last_cause = if done.cause == StopCause::Requested && self.is_shutdown() {
1258                        StopCause::SystemShutdown
1259                    } else {
1260                        done.cause
1261                    };
1262                    last_detail = None;
1263                    break;
1264                }
1265                GenOutcome::Panicked { detail } => {
1266                    last_detail = detail;
1267                    match self.policy {
1268                        RestartPolicy::Permanent => {
1269                            last_cause = StopCause::Panicked;
1270                            break;
1271                        }
1272                        RestartPolicy::Transient {
1273                            max_restarts,
1274                            backoff,
1275                            reset_after,
1276                        } => {
1277                            let now = self.system.now();
1278                            if last_failure.is_some_and(|t| now - t >= reset_after) {
1279                                self.restarts = 0; // 恢复窗口:清零重启计数
1280                            }
1281                            self.restarts += 1;
1282                            last_failure = Some(now);
1283                            if !self.source.is_renewable() || self.restarts > max_restarts {
1284                                last_cause = StopCause::ResourceLimit;
1285                                break;
1286                            }
1287                            let shift = (self.restarts - 1).min(10);
1288                            let delay = backoff.saturating_mul(1u32 << shift);
1289                            tracing::warn!(
1290                                actor = %self.id,
1291                                restart = self.restarts,
1292                                ?delay,
1293                                "Actor 事件循环 panic,按监督策略重启"
1294                            );
1295                            // 重启空窗对外可见(地面站 UI:链路重连中)
1296                            publish_phase(
1297                                &self.stop_tx,
1298                                ActorPhase::Restarting {
1299                                    generation: self.generation + 1,
1300                                    attempt: self.restarts,
1301                                },
1302                            );
1303                            if !self.wait_backoff(delay).await {
1304                                last_cause = if self.is_shutdown() {
1305                                    StopCause::SystemShutdown
1306                                } else {
1307                                    StopCause::Requested
1308                                };
1309                                last_detail = None;
1310                                break;
1311                            }
1312                            continue;
1313                        }
1314                    }
1315                }
1316            }
1317        }
1318
1319        self.guard.finalize(last_cause, last_detail);
1320    }
1321
1322    /// 取下一世代实例。
1323    ///
1324    /// 工厂为用户代码:panic 在此被 `catch_unwind` 捕获为
1325    /// [`SourceTaken::FactoryPanicked`],交由调用方按世代 panic 同一
1326    /// 路径处置(退避重试/超限终止),不炸毁 supervisor 任务。
1327    fn take_actor(&mut self) -> SourceTaken<A> {
1328        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.source.take())) {
1329            Ok(Some(a)) => SourceTaken::Ready(a),
1330            Ok(None) => SourceTaken::Exhausted,
1331            Err(payload) => SourceTaken::FactoryPanicked(payload_text(payload)),
1332        }
1333    }
1334
1335    /// 运行一个世代;返回退出结果或 panic 标记。
1336    async fn run_one_generation(&mut self, actor: A) -> GenOutcome {
1337        // 相位回到 Running:重启空窗(Restarting)结束的可观测点。
1338        // 首世代为 no-op(初值即 Running,publish_phase 内做等值短路)
1339        publish_phase(&self.stop_tx, ActorPhase::Running);
1340        let ctx = ActorContext::new(
1341            self.system.clone(),
1342            self.id,
1343            self.name.clone(),
1344            self.ctl_tx.clone(),
1345            self.stop_tx.clone(),
1346            self.sig_tx.clone(),
1347            self.generation,
1348            self.restarts,
1349        );
1350        let gen = Generation {
1351            actor,
1352            ctx,
1353            mailbox: self.mailbox.clone(),
1354            sigbox: self.sigbox.clone(),
1355            slot_rx: self.slot_rx.clone(),
1356            stop_rx: self.stop_rx.clone(),
1357        };
1358        let (done_tx, done_rx) = oneshot::channel::<GenDone>();
1359        let jh = tokio::spawn(async move {
1360            let done = gen.run().await;
1361            let _ = done_tx.send(done);
1362        });
1363        // 发布 abort 句柄(宽限超时强杀用)。世代结束即清空:避免对
1364        // 已完成任务执行无意义的 abort,也避免陈旧句柄被误用
1365        *self.abort.lock().unwrap_or_else(|e| e.into_inner()) = Some(jh.abort_handle());
1366        let outcome = match done_rx.await {
1367            Ok(done) => GenOutcome::Exited(done),
1368            Err(_) => {
1369                // 发送端随任务销毁:等待任务收尾并区分 panic 与其他取消
1370                match jh.await {
1371                    Err(je) if je.is_panic() => GenOutcome::Panicked {
1372                        detail: panic_detail(je),
1373                    },
1374                    _ => GenOutcome::Exited(GenDone {
1375                        cause: StopCause::Requested,
1376                    }),
1377                }
1378            }
1379        };
1380        *self.abort.lock().unwrap_or_else(|e| e.into_inner()) = None;
1381        outcome
1382    }
1383
1384    /// 退避等待;返回 false 表示期间收到停止/关闭信号。
1385    ///
1386    /// 走系统注入时钟(与定时器/看门狗同源),虚拟时间测试可确定推进。
1387    async fn wait_backoff(&mut self, delay: Duration) -> bool {
1388        let deadline = deadline_after(self.system.now(), delay);
1389        let clock = self.system.inner.clock.clone();
1390        // 先消费版本并立即复核停止位:调用方刚发布的 Restarting 是本接收端
1391        // 的"自写",若留到 select 内,changed() 会立即返回并按值误判;
1392        // 而在发布与本复核之间落值的停止请求同样不丢(此处即读到 Stopped)。
1393        if matches!(
1394            &*self.stop_rx.borrow_and_update(),
1395            ActorPhase::Stopped { .. }
1396        ) {
1397            return false;
1398        }
1399        tokio::select! {
1400            biased;
1401            _ = self.stop_rx.changed() => !matches!(
1402                &*self.stop_rx.borrow_and_update(),
1403                ActorPhase::Stopped { .. }
1404            ),
1405            _ = self.shutdown_rx.changed() => !self.is_shutdown(),
1406            _ = clock.sleep_until(deadline) => true,
1407        }
1408    }
1409
1410    fn is_shutdown(&self) -> bool {
1411        self.system.is_shutdown()
1412    }
1413}
1414
1415/// 最终退出守卫:注销注册表 → 清理 watch 双索引 → 通知 watchers → 触发 exit 信号。
1416///
1417/// 正常路径由 [`Supervisor::run`] 显式调用 [`finalize`](Self::finalize);
1418/// supervisor 任务因未捕获 panic 展开(如 runtime 关闭时 `tokio::spawn`
1419/// 失败、自定义时钟实现 panic)被丢弃时,由 [`Drop`] 以 Panicked 原因兜底 ——
1420/// 保证注册表条目/名称/终止通知在任何退出方式下都恰好清理一次。
1421struct FinalizeGuard {
1422    system: ActorSystem,
1423    id: ActorId,
1424    name: Option<ActorName>,
1425    exit_tx: watch::Sender<bool>,
1426    /// 相位通道发送端:终态在此写入(详见 [`finalize`](Self::finalize))。
1427    stop_tx: Arc<watch::Sender<ActorPhase>>,
1428    done: bool,
1429}
1430
1431impl FinalizeGuard {
1432    fn finalize(&mut self, cause: StopCause, detail: Option<String>) {
1433        if self.done {
1434            return;
1435        }
1436        self.done = true;
1437        let inner = self.system.inner.clone();
1438        // 顺序契约:必须先注销 registry、后摘除 by_name(与 spawn 侧插入
1439        // 顺序相反)。SystemInner::register_name 以"registry 无此 id"判定
1440        // 陈旧条目;反序会让存活条目的名称被误判为陈旧而遭顶替。
1441        inner.registry.remove(&self.id);
1442        if let Some(n) = &self.name {
1443            inner.by_name.remove_if(n, |_, &cur| cur == self.id);
1444        }
1445        // 作为 watcher 的登记全局清理:覆盖跨世代的全部登记
1446        // (不依赖单个世代的本地列表 —— panic 世代不丢失)
1447        inner.cleanup_watcher(self.id);
1448        let terminated = Terminated {
1449            actor: self.id,
1450            name: self.name.clone(),
1451            cause,
1452            detail,
1453        };
1454        if let Some((_, watchers)) = inner.watched_by.remove(&self.id) {
1455            for w in watchers {
1456                inner.push_signal(w, ActorSignal::Terminated(terminated.clone()));
1457            }
1458        }
1459        tracing::debug!(actor = %self.id, %cause, "Actor 已最终退出");
1460        // 终态相位先于退出信号写入(stop_and_wait 返回即可查到死因)。
1461        // send_replace 无条件落值:既覆盖此前的"停止请求"占位(真实死因
1462        // 优先),又在零接收端下照常保留 —— 死后补订阅仍读到终态。
1463        let _ = self.stop_tx.send_replace(ActorPhase::Stopped {
1464            cause,
1465            detail: terminated.detail.clone(),
1466        });
1467        let _ = self.exit_tx.send(true);
1468    }
1469}
1470
1471impl Drop for FinalizeGuard {
1472    fn drop(&mut self) {
1473        self.finalize(
1474            StopCause::Panicked,
1475            Some("监督任务异常退出(未捕获 panic 或 runtime 关闭)".to_string()),
1476        );
1477    }
1478}
1479
1480// ---------------------------------------------------------------------------
1481// 世代事件循环
1482// ---------------------------------------------------------------------------
1483
1484struct Generation<A: Actor> {
1485    actor: A,
1486    ctx: ActorContext<A::Message>,
1487    mailbox: Arc<tokio::sync::Mutex<mpsc::Receiver<A::Message>>>,
1488    sigbox: Arc<tokio::sync::Mutex<mpsc::Receiver<Signal>>>,
1489    slot_rx: Option<SlotReader<A::Message>>,
1490    stop_rx: watch::Receiver<ActorPhase>,
1491}
1492
1493impl<A: Actor> Generation<A> {
1494    async fn run(self) -> GenDone {
1495        let id = self.ctx.id();
1496        // 世代任务全程携带"我是谁"标记:shutdown 自调用排除与
1497        // ask / stop_and_wait 自调用 fail-fast 均依赖它
1498        GENERATION_ACTOR.scope(id, self.run_scoped()).await
1499    }
1500
1501    /// 世代主体,恒在 [`GENERATION_ACTOR`] 作用域内执行。
1502    async fn run_scoped(self) -> GenDone {
1503        let Generation {
1504            mut actor,
1505            mut ctx,
1506            mailbox,
1507            sigbox,
1508            mut slot_rx,
1509            mut stop_rx,
1510        } = self;
1511        // 信箱租约:一个世代只允许一条事件循环持有(重启串行化保证)。
1512        let mut rx = mailbox.lock().await;
1513        let mut sig = sigbox.lock().await;
1514
1515        if ctx.restarts() > 0 {
1516            // 监督重启后的新世代:先向新实例告知重启序号,再走通用启动钩子
1517            let attempt = ctx.restarts();
1518            actor.on_restart(attempt, &mut ctx).await;
1519        }
1520        actor.on_start(&mut ctx).await;
1521
1522        // 所有 `break 'gen` 路径均先赋值(无默认初值冷路径)
1523        let cause;
1524        'gen: loop {
1525            // 控制面永远优先(停机可能发生在世代启动之前)
1526            if matches!(&*stop_rx.borrow_and_update(), ActorPhase::Stopped { .. }) {
1527                cause = StopCause::Requested;
1528                break 'gen;
1529            }
1530            // 信号优先抽干:Terminated 等控制面通知走专用通道,
1531            // 绝不排队在用户消息积压之后(失控保护延迟有界)
1532            while let Ok(s) = sig.try_recv() {
1533                if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
1534                    cause = StopCause::Requested;
1535                    break 'gen;
1536                }
1537            }
1538            // 数据端口启动补拉:消费停机期间写入的帧(只关心最新)
1539            if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
1540                if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
1541                    cause = StopCause::Requested;
1542                    break 'gen;
1543                }
1544            }
1545            tokio::select! {
1546                biased;
1547                // 1. 控制面停止 —— 统一由循环顶部判定退出
1548                _ = stop_rx.changed() => continue 'gen,
1549                // 2. 信号通道(专用,独立于用户消息积压)
1550                s = sig.recv() => {
1551                    if let Some(s) = s {
1552                        if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
1553                            cause = StopCause::Requested;
1554                            break 'gen;
1555                        }
1556                    } else {
1557                        // None:信号通道关闭。全部发送端(Entry / Supervisor / ctx)
1558                        // 均不存活才会发生,而世代运行期间 Supervisor 与 ctx 恒持
1559                        // 发送端,故此分支理论不可达(信号通道与世代同生命周期)。
1560                        // 若出现则记录自诊断;控制通道此刻也即将关闭,下一轮
1561                        // 将经 rx.recv() 返回 None 退出世代,不会忙循环。
1562                        tracing::error!(actor = %ctx.id(), "信号通道意外关闭(理论不可达)");
1563                    }
1564                }
1565                // 3. 控制通道(用户消息,批量抽取 ≤ SELF_BATCH_LIMIT)
1566                msg = rx.recv() => {
1567                    let Some(mut msg) = msg else {
1568                        cause = StopCause::MailboxClosed;
1569                        break 'gen;
1570                    };
1571                    let mut drained = 1usize;
1572                    loop {
1573                        if actor.handle(msg, &mut ctx).await == ActorAction::Stop {
1574                            cause = StopCause::Requested;
1575                            break 'gen;
1576                        }
1577                        // 批量:抽干已到达消息,但给停止/数据帧留出穿插点
1578                        if drained >= SELF_BATCH_LIMIT {
1579                            break;
1580                        }
1581                        // 批内穿插:抽干信号通道并检查停止位 —— 控制面通知
1582                        //(含看门狗触发)最多等待一条用户消息,而非整批
1583                        //(64 条慢消息可达秒级)
1584                        while let Ok(s) = sig.try_recv() {
1585                            if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
1586                                cause = StopCause::Requested;
1587                                break 'gen;
1588                            }
1589                        }
1590                        // 停止位检查先于补帧:`ctx.stop()` 契约是"当前消息
1591                        // 处理后不再交付任何新消息"—— 若检查停在补帧之后,
1592                        // 批内消息请求停止后仍会多交付一条数据帧
1593                        if matches!(&*stop_rx.borrow(), ActorPhase::Stopped { .. }) {
1594                            cause = StopCause::Requested;
1595                            break 'gen;
1596                        }
1597                        // 穿插点同样补拉数据端口最新帧:消息洪泛下最新
1598                        // 遥测帧的延迟与失控保护同阶(≤1 条用户消息),
1599                        // 而非被整批(64 条)慢消息推迟
1600                        if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
1601                            if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
1602                                cause = StopCause::Requested;
1603                                break 'gen;
1604                            }
1605                            // 该帧自身请求停止(ctx.stop):同样不得再取
1606                            // 下一条消息
1607                            if matches!(&*stop_rx.borrow(), ActorPhase::Stopped { .. }) {
1608                                cause = StopCause::Requested;
1609                                break 'gen;
1610                            }
1611                        }
1612                        drained += 1;
1613                        match rx.try_recv() {
1614                            Ok(m) => msg = m,
1615                            Err(_) => break,
1616                        }
1617                    }
1618                }
1619                // 4. 数据端口最新帧(含写端全部消失后遗留的最后一帧)
1620                _ = wait_slot(&mut slot_rx) => {
1621                    if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
1622                        if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
1623                            cause = StopCause::Requested;
1624                            break 'gen;
1625                        }
1626                    }
1627                }
1628            }
1629        }
1630
1631        // 释放信箱租约后再执行收尾钩子(重启场景可尽早交接)
1632        drop(rx);
1633        drop(sig);
1634        actor.on_stop(&mut ctx).await;
1635        GenDone { cause }
1636    }
1637}
1638
1639/// 分发一条信号通道消息(事件循环全部投递点的唯一入口)。
1640async fn deliver_signal<A: Actor>(
1641    actor: &mut A,
1642    ctx: &mut ActorContext<A::Message>,
1643    signal: Signal,
1644) -> ActorAction {
1645    match signal {
1646        // 看门狗触发标记:与当前武装世代比对,已被喂狗/再武装/解除取代
1647        // 的陈旧触发静默丢弃;新鲜触发将超时消息投递给 handle
1648        //(不经 on_signal —— 失控保护是消息处理而非信号回调)。
1649        Signal::WatchdogFire { arm } => match ctx.take_watchdog_fire(arm) {
1650            Some(msg) => actor.handle(msg, ctx).await,
1651            None => ActorAction::Continue,
1652        },
1653        Signal::System(sig) => {
1654            // Terminated 送达前先自愈 watcher 侧登记(ctx.watched + 全局
1655            // watching/watched_by 双索引):目标既已终止且 ID 不复用,残留登记
1656            // 只余泄漏价值。该自愈使 watch 回归真正的一次性语义,并消除
1657            // "长命 watcher 反复监视短命目标"(重连的链路会话)造成的
1658            // 无上界累积与 register_watch 的 O(n²) 退化。
1659            //
1660            // ActorSignal 当前单变体;若未来增加变体,此处会编译失败并提醒补全自愈分支
1661            let ActorSignal::Terminated(t) = &sig;
1662            ctx.reap_watch(t.actor);
1663            actor.on_signal(sig, ctx).await
1664        }
1665    }
1666}
1667
1668/// 数据端口等待:返回 true 表示可能有待消费帧(调用方随后 `take_latest`)。
1669///
1670/// 写端全部 drop(遥测源消失)时的语义:
1671/// - **先补取最后一帧再挂起**:`changed()` 对已关闭通道直接返回 Err
1672///   且不携带值,若不补取,关闭前写入、尚未消费的最后一帧(如断链前
1673///   最后姿态)会被静默吞掉;
1674/// - 补取为空后转入永久挂起而非报错:
1675///   - 数据端口消失只表示“不再有帧”,控制通道仍然存活,
1676///     Actor 不得因此退出(端口关闭并非 MailboxClosed);
1677///   - `changed()` 对已关闭接收端会立即返回 Err,直接重试会
1678///     退化成忙循环 —— 永久挂起等价于把该分支从 select 摘除。
1679///
1680/// 可达性:注册表条目持 `ActorRef` 克隆(内含 `SlotWriter`),Actor 存活
1681/// 期间写端不会全部消失;强制注销路径又总伴随停止请求(事件循环在循环
1682/// 顶部先行退出)。故关闭分支属防御性代码,保留以杜绝未来变更下的忙循环,
1683/// 其行为由本模块单元测试 `wait_slot_on_closed_port_drains_last_frame_then_hangs`
1684/// 直接固化。
1685async fn wait_slot<M: ActorMsg>(slot_rx: &mut Option<SlotReader<M>>) -> bool {
1686    match slot_rx {
1687        Some(r) => {
1688            if r.changed().await.is_ok() {
1689                return true;
1690            }
1691            if r.take_latest().is_some() {
1692                return true;
1693            }
1694            std::future::pending::<()>().await;
1695            unreachable!("pending() 永不完成")
1696        }
1697        None => {
1698            std::future::pending::<()>().await;
1699            unreachable!("pending() 永不完成")
1700        }
1701    }
1702}
1703
1704#[cfg(test)]
1705mod tests {
1706    use super::*;
1707    use crate::ctx::ActorContext;
1708
1709    /// Terminated 送达路径的 watcher 侧自愈(F1 回归):
1710    /// reap_watch 清除 watching/watched_by 双向登记,重复 reap 为 no-op。
1711    #[tokio::test]
1712    async fn reap_watch_clears_both_indexes() {
1713        let system = ActorSystem::new();
1714        let watcher = ActorId::new(900);
1715        let target = ActorId::new(901);
1716        system.inner.register_watch(watcher, target);
1717        assert_eq!(
1718            system.inner.watching.get(&watcher).map(|l| l.len()),
1719            Some(1),
1720            "登记后 watching 应持有目标"
1721        );
1722        assert_eq!(
1723            system.inner.watched_by.get(&target).map(|l| l.len()),
1724            Some(1),
1725            "登记后 watched_by 应持有 watcher"
1726        );
1727
1728        let (ctl_tx, _ctl_rx) = mpsc::channel::<u64>(1);
1729        let (stop_tx, _stop_rx) = watch::channel(ActorPhase::Running);
1730        let (sig_tx, _sig_rx) = mpsc::channel::<Signal>(1);
1731        let mut ctx: ActorContext<u64> = ActorContext::new(
1732            system.clone(),
1733            watcher,
1734            None,
1735            ctl_tx,
1736            Arc::new(stop_tx),
1737            sig_tx,
1738            1,
1739            0,
1740        );
1741        ctx.reap_watch(target);
1742        ctx.reap_watch(target); // 重复 reap 必须 no-op
1743
1744        assert!(
1745            system.inner.watching.get(&watcher).is_none(),
1746            "reap 后 watching 登记应被清除"
1747        );
1748        assert!(
1749            system.inner.watched_by.get(&target).is_none(),
1750            "reap 后 watched_by 登记应被清除"
1751        );
1752        system.shutdown().await;
1753    }
1754
1755    /// 回归:**未 shutdown** 丢弃最后一个用户句柄(且仍有 Actor 注册)
1756    /// 必须 warn;正常 shutdown 后丢弃句柄不得误报。
1757    ///
1758    /// 经 `tracing_subscriber` 捕获实际日志文本断言 —— 计数/跟踪标记
1759    /// 属于易静默失效的机制(内部持有者若被误跟踪则永远不告警)。
1760    #[test]
1761    fn dropping_last_handle_without_shutdown_warns() {
1762        /// 累积日志文本的线程安全 writer。
1763        #[derive(Clone)]
1764        struct Buf(Arc<std::sync::Mutex<Vec<u8>>>);
1765        impl Buf {
1766            fn text(&self) -> String {
1767                String::from_utf8_lossy(&self.0.lock().unwrap()).into_owned()
1768            }
1769        }
1770        impl std::io::Write for Buf {
1771            fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
1772                self.0.lock().unwrap().extend_from_slice(data);
1773                Ok(data.len())
1774            }
1775            fn flush(&mut self) -> std::io::Result<()> {
1776                Ok(())
1777            }
1778        }
1779        impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Buf {
1780            type Writer = Buf;
1781            fn make_writer(&'a self) -> Buf {
1782                self.clone()
1783            }
1784        }
1785
1786        struct Nop;
1787        impl Actor for Nop {
1788            type Message = u32;
1789            async fn handle(&mut self, _m: u32, _c: &mut ActorContext<u32>) -> ActorAction {
1790                ActorAction::Continue
1791            }
1792        }
1793
1794        let buf = Buf(Arc::new(std::sync::Mutex::new(Vec::new())));
1795        let subscriber = tracing_subscriber::fmt()
1796            .with_writer(buf.clone())
1797            .with_ansi(false)
1798            .with_max_level(tracing::Level::WARN)
1799            .finish();
1800        let rt = tokio::runtime::Builder::new_current_thread()
1801            .enable_all()
1802            .build()
1803            .unwrap();
1804
1805        tracing::subscriber::with_default(subscriber, || {
1806            rt.block_on(async {
1807                // 场景一:Actor 存活且未 shutdown,丢弃最后一个句柄 → 必须告警
1808                let system = ActorSystem::new();
1809                let leaked = system.spawn_anonymous(Nop).unwrap();
1810                drop(system);
1811
1812                // 场景二:先 shutdown 再丢弃全部句柄 → 不得告警
1813                let system = ActorSystem::new();
1814                let graceful = system.spawn_anonymous(Nop).unwrap();
1815                system.shutdown().await;
1816                drop(graceful);
1817                drop(system);
1818
1819                drop(leaked);
1820            });
1821        });
1822
1823        let logs = buf.text();
1824        assert_eq!(
1825            logs.matches("未调用 shutdown").count(),
1826            1,
1827            "仅未 shutdown 的丢弃应告警一次;实际日志:{logs}"
1828        );
1829    }
1830
1831    /// 数据端口关闭分支(防御性路径)的直接覆盖:写端消失时先补投槽内
1832    /// 最后一帧,随后转为永久挂起(不得返回、不得忙循环、不得视为关闭)。
1833    #[tokio::test]
1834    async fn wait_slot_on_closed_port_drains_last_frame_then_hangs() {
1835        let (w, r) = latest_slot::<u32>();
1836        w.send(7);
1837        drop(w);
1838
1839        let mut slot = Some(r);
1840        assert!(wait_slot(&mut slot).await, "关闭前最后一帧必须被补取");
1841        assert_eq!(slot.as_mut().unwrap().take_latest(), Some(7));
1842
1843        let hung = tokio::time::timeout(Duration::from_millis(50), wait_slot(&mut slot)).await;
1844        assert!(hung.is_err(), "空槽 + 写端消失必须永久挂起而非返回");
1845
1846        let mut none: Option<SlotReader<u32>> = None;
1847        let hung = tokio::time::timeout(Duration::from_millis(50), wait_slot(&mut none)).await;
1848        assert!(hung.is_err(), "无数据端口的 Actor 必须永久挂起");
1849    }
1850}